Update version to 0.11.0

0.9.5 depended on Node 0.11+, so make sure we don't ever get that.
See https://github.com/reactjs/commoner/pull/65

.editorconfig

@@ -12,3 +12,6 @@ trim_trailing_whitespace = true
 [*.md]
 max_line_length = 0
 trim_trailing_whitespace = false
+
+[COMMIT_EDITMSG]
+max_line_length = 0

.mailmap

@@ -1,12 +1,26 @@
 Ben Newman <bn@cs.stanford.edu> <benjamn@fb.com>
+Bill Fisher <fisherwebdev@gmail.com>
 Cheng Lou <chenglou92@gmail.com> <chenglou@fb.com>
 Christoph Pojer <christoph.pojer@gmail.com>
 Christoph Pojer <christoph.pojer@gmail.com> <cpojer@fb.com>
 Connor McSheffrey <c@conr.me> <connor.mcsheffrey@gmail.com>
 Dan Schafer <dschafer@fb.com>
+Daniel Gasienica <daniel@gasienica.ch> <daniel@fiftythree.com>
+Daniel Gasienica <daniel@gasienica.ch> <dgasienica@zynga.com>
+Daniel Lo Nigro <daniel@dan.cx> <danlo@fb.com>
+Evan Coonrod <evan@paloalto.com>
 Fabio M. Costa <fabiomcosta@gmail.com> <fabs@fb.com>
+Felix Kling <felix.kling@gmx.net> <fkling@fb.com>
+François-Xavier Bois <fxbois@gmail.com>
+Geert Pasteels <geert.pasteels@gmail.com>
+George A Sisco III <george.sisco@gmail.com>
 Harry Hull <harry.hull1@gmail.com>
+Hendrik Swanepoel <hendrik.swanepoel@gmail.com>
 Ingvar Stepanyan <me@rreverser.com> <rreverser@ubuntu.rreverser.a4.internal.cloudapp.net>
+Irae Carvalho <irae@irae.pro.br>
+Jaime Mingo <j.mingov@3boll.com>
+James Brantly <james@jbrantly.com>
+Jan Kassens <jan@kassens.net> <jkassens@fb.com>
 Jason Bonta <jbonta@gmail.com> <jasonbonta@fb.com>
 Jason Trill <jason@jasontrill.com>
 Jeff Morrison <jeff@anafx.com> <Jeff@anafx.com>
@@ -18,8 +32,10 @@ Jordan Walke <jordojw@gmail.com> <jordanjcw@fb.com>
 Josh Duck <josh@fb.com> <github@joshduck.com>
 Jun Wu <quark@lihdd.net>
 Keito Uchiyama <projects@keito.me> <keito@fb.com>
+Kunal Mehta <k.mehta@berkeley.edu> <kunalm@fb.com>
 Laurence Rowe <l@lrowe.co.uk> <laurence@lrowe.co.uk>
 Martin Andert <mandert@gmail.com>
+Mathieu M-Gosselin <mathieumg@gmail.com> <mathieumg@atx33.com>
 Michal Srb <xixixao@seznam.cz> xixixao <xixixao@seznam.cz>
 Nick Gavalas <njg57@cornell.edu>
 Nick Thompson <ncthom91@gmail.com> <nickt@instagram.com>
@@ -30,7 +46,9 @@ Pete Hunt <floydophone@gmail.com> <pete.hunt@fb.com>
 Pete Hunt <floydophone@gmail.com> <pete@instagram.com>
 Pete Hunt <floydophone@gmail.com> <phunt@instagram.com>
 Petri Lievonen <plievone@cc.hut.fi>
+Petri Lievonen <plievone@cc.hut.fi> <petri.lievonen@tkk.fi>
 Pieter Vanderwerff <me@pieter.io> <pieter@heyday.co.nz>
+Ray <ray@tomo.im>
 Richard Feldman <richard.t.feldman@gmail.com> <richard@noredink.com>
 Richard Livesey <Livesey7@hotmail.co.uk>
 Sander Spies <sandermail@gmail.com>
@@ -40,3 +58,5 @@ Thomas Aylott <oblivious@subtlegradient.com> <aylott@fb.com>
 Timothy Yung <yungsters@gmail.com> <yungsters@fb.com>
 Vjeux <vjeuxx@gmail.com>
 Vjeux <vjeuxx@gmail.com> <vjeux@fb.com>
+Volkan Unsal <spocksplanet@gmail.com>
+Zach Bruggeman <mail@bruggie.com> <zbruggeman@me.com>

.travis.yml

@@ -2,12 +2,15 @@
 language: node_js
 node_js:
 - '0.10'
+cache:
+  directories:
+  - node_modules
 script:
 - |
     grunt $TEST_TYPE
 after_script:
 - |
-    if [ "$TEST_TYPE" = test:full ] && [ "$SERVER" ]; then
+    if [ "$TEST_TYPE" = test ] && [ "$SERVER" ]; then
       grunt build
       curl \
         -F "react=@build/react.js" \
@@ -26,16 +29,9 @@ after_script:
     fi
 env:
   matrix:
-  - TEST_TYPE=test:full
+  - TEST_TYPE=test
   - TEST_TYPE=lint
-  - TEST_TYPE=perf:full
-  - TEST_TYPE=test:coverage
-  - TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie11
-  - TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie10
-  - TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie9
-  - TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie8
-  - TEST_TYPE=test:webdriver:saucelabs:ios
-  - TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=safari
+  - TEST_TYPE=test:webdriver:saucelabs:modern
   global:
   # SERVER
   - secure: qPvsJ46XzGrdIuPA70b55xQNGF8jcK7N1LN5CCQYYocXLa+fBrl+fTE77QvehOPhqwJXcj6kOxI+sY0KrVwV7gmq2XY2HZGWUSCxTN0SZlNIzqPA80Y7G/yOjA4PUt8LKgP+8tptyhTAY56qf+hgW8BoLiKOdztYF2p+3zXOLuA=
@@ -47,6 +43,7 @@ matrix:
     - env: TEST_TYPE=lint
     - env: TEST_TYPE=test:coverage
     - env: TEST_TYPE=perf:full
+    - env: TEST_TYPE=test:webdriver:saucelabs:modern
     - env: TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie11
     - env: TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie10
     - env: TEST_TYPE=test:webdriver:saucelabs BROWSER_NAME=ie9

AUTHORS

@@ -1,3 +1,5 @@
+Adam Krebs <amk528@cs.nyu.edu>
+Adam Solove <asolove@gmail.com>
 Alan deLevie <adelevie@gmail.com>
 Alex Zelenskiy <azelenskiy@fb.com>
 Alexander Solovyov <alexander@solovyov.net>
@@ -5,82 +7,131 @@ Andreas Svensson <andreas@syranide.com>
 Andrew Davey <andrew@equin.co.uk>
 Andrew Zich <azich@fb.com>
 Andrey Popp <8mayday@gmail.com>
+Anthony van der Hoorn <anthony.vanderhoorn@gmail.com>
 Ayman Osman <aymano.osman@gmail.com>
 Ben Alpert <spicyjalapeno@gmail.com>
 Ben Newman <bn@cs.stanford.edu>
 Ben Ripkens <bripkens.dev@gmail.com>
+Bill Fisher <fisherwebdev@gmail.com>
 Bob Eagan <bob@synapsestudios.com>
+Bojan Mihelac <bmihelac@mihelac.org>
+Brandon Bloom <brandon@brandonbloom.name>
 Brian Cooke <bri@bricooke.com>
 Brian Kim <briankimpossible@gmail.com>
+Brian Reavis <brian@thirdroute.com>
 Brian Rue <brian@rollbar.com>
 Cam Spiers <camspiers@gmail.com>
+Cassus Adam Banko <banko.adam@gmail.com>
 Cat Chen <catchen@fb.com>
 Cheng Lou <chenglou92@gmail.com>
 Christian Roman <chroman16@gmail.com>
 Christoph Pojer <christoph.pojer@gmail.com>
+Christopher Monsanto <chris@monsan.to>
 Clay Allsopp <clay.allsopp@gmail.com>
 Connor McSheffrey <c@conr.me>
 Dan Schafer <dschafer@fb.com>
-Daniel Gasienica <dgasienica@zynga.com>
-Daniel Lo Nigro <danlo@fb.com>
+Daniel Gasienica <daniel@gasienica.ch>
+Daniel Lo Nigro <daniel@dan.cx>
 Daniel Miladinov <dmiladinov@wingspan.com>
+Daniel Schonfeld <daniel@schonfeld.org>
 Danny Ben-David <dannybd@fb.com>
+Daryl Lau <daryl@weak.io>
 David Hellsing <david@aino.se>
 David Hu <davidhu91@gmail.com>
+Devon Blandin <dblandin@gmail.com>
+Dmitry Mazuro <dmitry.mazuro@icloud.com>
 Dustin Getz <dgetz@wingspan.com>
+Enguerran <engcolson@gmail.com>
 Eric Clemmons <eric@smarterspam.com>
+Eric Florenzano <floguy@gmail.com>
 Eric Schoffstall <contra@wearefractal.com>
+Evan Coonrod <evan@paloalto.com>
 Fabio M. Costa <fabiomcosta@gmail.com>
 Felipe Oliveira Carvalho <felipekde@gmail.com>
-Felix Kling <fkling@fb.com>
+Felix Kling <felix.kling@gmx.net>
 Fernando Correia <fernando@servicero.com>
+François-Xavier Bois <fxbois@gmail.com>
+Fred Zhao <fredz@fb.com>
+G Scott Olson <gscottolson@gmail.com>
+Geert Pasteels <geert.pasteels@gmail.com>
+Geert-Jan Brits <gbrits@gmail.com>
+George A Sisco III <george.sisco@gmail.com>
+Gilbert <gilbertbgarza@gmail.com>
+Greg Hurrell <glh@fb.com>
 Greg Roodt <groodt@gmail.com>
+Guangqiang Dong <gqdong@fb.com>
 Guido Bouman <m@guido.vc>
 Harry Hull <harry.hull1@gmail.com>
+Harshad Sabne <harshadsabne@users.noreply.github.com>
+Hendrik Swanepoel <hendrik.swanepoel@gmail.com>
 Hugo Jobling <me@thisishugo.com>
 Ian Obermiller <iano@fb.com>
 Ingvar Stepanyan <me@rreverser.com>
+Irae Carvalho <irae@irae.pro.br>
 Isaac Salier-Hellendag <isaac@fb.com>
 Ivan Kozik <ivan@ludios.org>
+Jaime Mingo <j.mingov@3boll.com>
 Jakub Malinowski <jakubmal@gmail.com>
+James Brantly <james@jbrantly.com>
 James Ide <ide@fb.com>
 Jamie Wong <jamie.lf.wong@gmail.com>
 Jamison Dance <jergason@gmail.com>
-Jan Kassens <jkassens@fb.com>
+Jan Kassens <jan@kassens.net>
 Jared Forsyth <jared@jaredforsyth.com>
 Jason Bonta <jbonta@gmail.com>
 Jason Trill <jason@jasontrill.com>
 Jean Lauliac <lauliacj@gmail.com>
+Jeff Barczewski <jeff.barczewski@gmail.com>
+Jeff Carpenter <gcarpenterv@gmail.com>
 Jeff Morrison <jeff@anafx.com>
+Jeff Welch <whatthejeff@gmail.com>
 Jeffrey Lin <lin.jeffrey@gmail.com>
 Jignesh Kakadiya <jigneshhk1992@gmail.com>
+Jing Chen <jingc@fb.com>
 Johannes Baiter <johannes.baiter@gmail.com>
 John Watson <jwatson@fb.com>
+Jon Beebe <jon.beebe@daveramsey.com>
+Jonas Enlund <jonas.enlund@gmail.com>
 Jonas Gebhardt <jonas@instagram.com>
 Jonathan Hsu <jhiswin@gmail.com>
 Jordan Walke <jordojw@gmail.com>
+Josh Bassett <josh.bassett@gmail.com>
 Josh Duck <josh@fb.com>
+Josh Yudaken <yud@instagram.com>
+Joshua Ma <me@joshma.com>
+Julen Ruiz Aizpuru <julenx@gmail.com>
 Jun Wu <quark@lihdd.net>
+Juraj Dudak <jdudak@fb.com>
+Justin Jaffray <justinjaffray@khanacademy.org>
+Karl Mikkelsen <karl@kingkarl.com>
 Keito Uchiyama <projects@keito.me>
 Kit Randel <kit@nocturne.net.nz>
 Kunal Mehta <k.mehta@berkeley.edu>
+Kyle Mathews <mathews.kyle@gmail.com>
 Laurence Rowe <l@lrowe.co.uk>
 Levi McCallum <levi@levimccallum.com>
+Lily <qvang.j@gmail.com>
 Logan Allen <loganfynne@gmail.com>
 Luigy Leon <luichi.19@gmail.com>
+Marcin Kwiatkowski <marcin.kwiatkowski@hotmail.com>
+Marcin Szczepanski <marcins@gmail.com>
+Mariano Desanze <protronm@gmail.com>
 Mark Richardson <echo@fb.com>
 Marshall Roch <mroch@fb.com>
 Martin Andert <mandert@gmail.com>
 Martin Konicek <mkonicek@fb.com>
 Mathieu M-Gosselin <mathieumg@gmail.com>
 Matt Harrison <mt.harrison86@gmail.com>
+Matthew Dapena-Tretter <m@tthewwithanm.com>
 Matti Nelimarkka <matti.nelimarkka@hiit.fi>
 Michal Srb <xixixao@seznam.cz>
 Mouad Debbar <mdebbar@fb.com>
 Nadeesha Cabral <nadeesha.cabral@gmail.com>
+Nate Hunzaker <nate.hunzaker@gmail.com>
 Nicholas Bergson-Shilcock <me@nicholasbs.net>
 Nick Gavalas <njg57@cornell.edu>
 Nick Thompson <ncthom91@gmail.com>
+Niklas Boström <nbostrom@gmail.com>
 Owen Coutts <owenc@fb.com>
 Pascal Hartig <passy@twitter.com>
 Paul O’Shannessy <paul@oshannessy.com>
@@ -90,20 +141,38 @@ Pete Hunt <floydophone@gmail.com>
 Peter Cottle <pcottle@fb.com>
 Petri Lievonen <plievone@cc.hut.fi>
 Pieter Vanderwerff <me@pieter.io>
+Rajiv Tirumalareddy <rajivtreddy@gmail.com>
+Randall Randall <randall@randallsquared.com>
+Ray <ray@tomo.im>
 Richard D. Worth <rdworth@gmail.com>
 Richard Feldman <richard.t.feldman@gmail.com>
 Richard Livesey <Livesey7@hotmail.co.uk>
+Ryan Seddon <seddon.ryan@gmail.com>
+Sahat Yalkabov <sakhat@gmail.com>
 Sander Spies <sandermail@gmail.com>
 Sean Kinsey <oyvind@fb.com>
 Sebastian Markbåge <sebastian@calyptus.eu>
 Shaun Trennery <shaun.trennery@gmail.com>
 Simon Højberg <r.hackr@gmail.com>
+Stefan Dombrowski <sdo451@gmail.com>
+Stephen Murphy <smurphy3@apple.com>
 Stoyan Stefanov <ssttoo@ymail.com>
 Sundeep Malladi <sundeep.malladi@gmail.com>
+Sven Helmberger <fforw@gmx.de>
 Thomas Aylott <oblivious@subtlegradient.com>
+Thomas Boyt <thomas.boyt@venmo.com>
+Thomas Shaddox <thomas@heyzap.com>
+Thomas Shafer <thomasjshafer@gmail.com>
 Timothy Yung <yungsters@gmail.com>
+Tom Haggie <thaggie@gmail.com>
 Tom Occhino <tomocchino@gmail.com>
+Ville Immonen <ville.immonen@iki.fi>
 Vjeux <vjeuxx@gmail.com>
+Volkan Unsal <spocksplanet@gmail.com>
+Wayne Larsen <wayne@larsen.st>
 Wincent Colaiuta <win@wincent.com>
-Zach Bruggeman <zbruggeman@me.com>
+Yuriy Dybskiy <yuriy@dybskiy.com>
+Yuval Dekel <thedekel@fb.com>
+Zach Bruggeman <mail@bruggie.com>
+davidxi <davidgraycn@gmail.com>
 imagentleman <imagentlemail@gmail.com>

CHANGELOG.md

@@ -1,3 +1,27 @@
+## 0.10.0 (March 21, 2014)
+
+### React Core
+
+#### New Features
+* Added warnings to help migrate towards descriptors
+* Made it possible to server render without React-related markup (`data-reactid`, `data-react-checksum`). This DOM will not be mountable by React. [Read the docs for `React.renderComponentToStaticMarkup`](http://facebook.github.io/react/docs/top-level-api.html#react.rendercomponenttostaticmarkup)
+* Added support for more attributes:
+  * `srcSet` for `<img>` to specify images at different pixel ratios
+  * `textAnchor` for SVG
+
+#### Bug Fixes
+* Ensure all void elements don’t insert a closing tag into the markup.
+* Ensure `className={false}` behaves consistently
+* Ensure `this.refs` is defined, even if no refs are specified.
+
+### Addons
+
+* `update` function to deal with immutable data. [Read the docs](http://facebook.github.io/react/docs/update.html)
+
+### react-tools
+* Added an option argument to `transform` function. The only option supported is `harmony`, which behaves the same as `jsx --harmony` on the command line. This uses the ES6 transforms from [jstransform](https://github.com/facebook/jstransform).
+
+
 ## 0.9.0 (February 20, 2014)
 
 ### React Core

CONTRIBUTING.md

@@ -27,7 +27,7 @@ The core team will be monitoring for pull requests. When we get one, we'll run s
 
 In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username.
 
-Complete your CLA here: <https://developers.facebook.com/opensource/cla>
+Complete your CLA here: <https://code.facebook.com/cla>
 
 ## Bugs
 

Gruntfile.js

@@ -20,15 +20,14 @@ module.exports = function(grunt) {
     copy: require('./grunt/config/copy'),
     jsx: require('./grunt/config/jsx'),
     browserify: require('./grunt/config/browserify'),
-    populist: require('./grunt/config/populist'),
+    populist: require('./grunt/config/populist')(grunt),
     connect: require('./grunt/config/server')(grunt),
     "webdriver-jasmine": require('./grunt/config/webdriver-jasmine'),
     "webdriver-perf": require('./grunt/config/webdriver-perf'),
     npm: require('./grunt/config/npm'),
     clean: ['./build', './*.gem', './docs/_site', './examples/shared/*.js', '.module-cache'],
     jshint: require('./grunt/config/jshint'),
-    compare_size: require('./grunt/config/compare_size'),
-    complexity: require('./grunt/config/complexity')
+    compare_size: require('./grunt/config/compare_size')
   });
 
   grunt.config.set('compress', require('./grunt/config/compress'));
@@ -67,7 +66,8 @@ module.exports = function(grunt) {
 
   grunt.registerTask('npm-react:release', npmReactTasks.buildRelease);
   grunt.registerTask('npm-react:pack', npmReactTasks.packRelease);
-  grunt.registerTask('npm-react-tools:pack', npmReactToolsTasks.pack);
+  grunt.registerTask('npm-react-tools:release', npmReactToolsTasks.buildRelease);
+  grunt.registerTask('npm-react-tools:pack', npmReactToolsTasks.packRelease);
 
   grunt.registerTask('version-check', versionCheckTask);
 
@@ -150,6 +150,18 @@ module.exports = function(grunt) {
     'webdriver-jasmine:saucelabs_' + (process.env.BROWSER_NAME || 'ie8')
   ]);
 
+  grunt.registerTask('test:webdriver:saucelabs:modern', [
+    'build:test',
+    'build:basic',
+
+    'connect',
+    'sauce-tunnel',
+    'webdriver-jasmine:saucelabs_android',
+    'webdriver-jasmine:saucelabs_firefox',
+    'webdriver-jasmine:saucelabs_chrome',
+    'webdriver-jasmine:saucelabs_ie11'
+  ]);
+
   grunt.registerTask('test:webdriver:saucelabs:ie', [
     'build:test',
     'build:basic',
@@ -179,7 +191,20 @@ module.exports = function(grunt) {
     'test:webdriver:phantomjs',
     'coverage:parse'
   ]);
-  grunt.registerTask('test', ['build:test', 'build:basic', 'test:webdriver:phantomjs']);
+  grunt.registerTask('fasttest', function() {
+    if (grunt.option('debug')) {
+      grunt.task.run('build:test', 'connect:server:keepalive');
+    } else {
+      grunt.task.run('build:test', 'test:webdriver:phantomjs');
+    }
+  });
+  grunt.registerTask('test', function() {
+    if (grunt.option('debug')) {
+      grunt.task.run('build:test', 'build:basic', 'connect:server:keepalive');
+    } else {
+      grunt.task.run('build:test', 'build:basic', 'test:webdriver:phantomjs');
+    }
+  });
   grunt.registerTask('perf', ['build:perf', 'perf:webdriver:phantomjs']);
   grunt.registerTask('npm:test', ['build', 'npm:pack']);
 
@@ -196,6 +221,7 @@ module.exports = function(grunt) {
     'browserify:addonsMin',
     'npm-react:release',
     'npm-react:pack',
+    'npm-react-tools:release',
     'npm-react-tools:pack',
     'copy:react_docs',
     'compare_size'

README.md

@@ -1,4 +1,4 @@
-# [React](http://facebook.github.io/react) [![Build Status](https://travis-ci.org/facebook/react.png?branch=master)](https://travis-ci.org/facebook/react)
+# [React](http://facebook.github.io/react) [![Build Status](https://travis-ci.org/facebook/react.svg?branch=master)](https://travis-ci.org/facebook/react)
 
 React is a JavaScript library for building user interfaces.
 
@@ -8,10 +8,6 @@ React is a JavaScript library for building user interfaces.
 
 [Learn how to use React in your own project.](http://facebook.github.io/react/docs/getting-started.html)
 
-## The `react` npm package has recently changed!
-
-If you're looking for jeffbski's [React.js](https://github.com/jeffbski/autoflow) project, it's now in `npm` as `autoflow` rather than `react`.
-
 ## Examples
 
 We have several examples [on the website](http://facebook.github.io/react/). Here is the first one to get you started:
@@ -40,12 +36,12 @@ The fastest way to get started is to serve JavaScript from the CDN (also availab
 
 ```html
 <!-- The core React library -->
-<script src="http://fb.me/react-0.8.0.js"></script>
+<script src="http://fb.me/react-0.10.0.js"></script>
 <!-- In-browser JSX transformer, remove when pre-compiling JSX. -->
-<script src="http://fb.me/JSXTransformer-0.8.0.js"></script>
+<script src="http://fb.me/JSXTransformer-0.10.0.js"></script>
 ```
 
-We've also built a [starter kit](http://facebook.github.io/react/downloads/react-0.8.0.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code.
+We've also built a [starter kit](http://facebook.github.io/react/downloads/react-0.10.0.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code.
 
 If you'd like to use [bower](http://bower.io), it's as easy as:
 
@@ -87,6 +83,10 @@ We use grunt to automate many tasks. Run `grunt -h` to see a mostly complete lis
 ```sh
 # Build and run tests with PhantomJS
 grunt test
+# Build and run tests in your browser
+grunt test --debug
+# For speed, you can use fasttest and add --filter to only run one test
+grunt fasttest --filter=ReactIdentity
 # Lint the code with JSHint
 grunt lint
 # Wipe out build directory

bin/jsx

@@ -2,8 +2,7 @@
 // -*- mode: js -*-
 "use strict";
 
-var visitors = require('../vendor/fbtransform/visitors');
-var transform = require('jstransform').transform;
+var transform = require('../main').transform;
 
 require('commoner').version(
   require('../package.json').version
@@ -12,13 +11,14 @@ require('commoner').version(
 }).option(
   '--harmony',
   'Turns on JS transformations such as ES6 Classes etc.'
+).option(
+  '--source-map-inline',
+  'Embed inline sourcemap in transformed source'
 ).process(function(id, source) {
   // This is where JSX, ES6, etc. desugaring happens.
-  var visitorList;
-  if (this.options.harmony) {
-    visitorList = visitors.getAllVisitors();
-  } else {
-    visitorList = visitors.transformVisitors.react;
-  }
-  return transform(visitorList, source).code;
+  var options = {
+    harmony: this.options.harmony,
+    sourceMap: this.options.sourceMapInline
+  };
+  return transform(source, options);
 });

docs/404.md

@@ -0,0 +1,8 @@
+---
+layout: single
+title: Page Not Found
+---
+
+We couldn't find what you were looking for.
+
+Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

docs/README.md

@@ -55,7 +55,7 @@ $ rake watch # Automatically compiles as needed.
 
 The easiest way to do this is to have a separate clone of this repository, checked out to the `gh-pages` branch. We have a build step that expects this to be in a directory named `react-gh-pages` at the same depth as `react`. Then it's just a matter of running `grunt docs`, which will compile the site and copy it out to this repository. From there you can check it in.
 
-**Note:** This should only be done for new releases. You should create a tag corresponding to the relase tag in the main repository.
+**Note:** This should only be done for new releases. You should create a tag corresponding to the release tag in the main repository.
 
 ### Removing the Jekyll / Ruby Dependency
 

docs/_config.yml

@@ -13,7 +13,7 @@ redcarpet:
 pygments: true
 name: React
 markdown: redcarpet
-react_version: 0.9.0
+react_version: 0.10.0
 description: A JavaScript library for building user interfaces
 relative_permalinks: true
 paginate: 5

docs/_css/react.scss

@@ -4,9 +4,9 @@
 @import '_solarized';
 
 @mixin code-typography {
-  font-family: 'source-code-pro', Menlo, 'Courier New', Consolas, monospace;
-  font-size: 13px;
-  line-height: 20px;
+  font-family: 'source-code-pro', Menlo, Consolas, 'Courier New', monospace;
+  font-size: 0.8em;
+  line-height: 1.5;
 }
 
 $skinnyContentWidth: 650px;
@@ -224,10 +224,11 @@ h1, h2, h3, h4, h5, h6 {
     margin: 0;
   }
   ul ul {
-    margin-left: 20px;
+    margin: 6px 0 0 20px;
   }
   li {
-    margin: 0;
+    line-height: 16px;
+    margin: 0 0 6px;
   }
   h3 {
     text-transform: uppercase;
@@ -454,6 +455,11 @@ section.black content {
   padding-top: 20px;
   width: 1220px;
 
+  label.compiler-option {
+    display: block;
+    margin-top: 5px;
+  }
+
   #jsxCompiler {
     margin-top: 20px;
   }
@@ -560,6 +566,19 @@ figure {
   margin: 0 auto;
 }
 
+h1 {
+  // Contains .edit-page-link
+  @include clearfix;
+}
+
+.edit-page-link {
+  float: right;
+  font-size: 16px;
+  font-weight: normal;
+  line-height: 20px;
+  margin-top: 17px;
+}
+
 /* Blog */
 
 .post-list-item + .post-list-item {
@@ -683,7 +702,12 @@ p code {
 }
 
 .highlight pre code {
-  font-size: inherit;
+  /* Respect line-height defined in <code> styles above */
+  display: block;
+
+  /* Cancel out styles for `li code` in case we have a <pre> within an <li>. */
+  background: none;
+  padding: 0;
 }
 
 .highlight pre .lineno {

docs/_data/nav_docs.yml

@@ -53,6 +53,12 @@
       title: Test Utilities
     - id: clone-with-props
       title: Cloning Components
+    - id: update
+      title: Immutability Helpers
+    - id: pure-render-mixin
+      title: PureRenderMixin
+    - id: perf
+      title: Performance Tools
 - title: Reference
   items:
   - id: top-level-api
@@ -71,3 +77,9 @@
     title: Special Non-DOM Attributes
   - id: reconciliation
     title: Reconciliation
+- title: Flux
+  items:
+  - id: flux-overview
+    title: Flux Overview
+  - id: flux-todo-list
+    title: Flux Todo List

docs/_data/nav_tips.yml

@@ -30,3 +30,7 @@
     title: Communicate Between Components
   - id: expose-component-functions
     title: Expose Component Functions
+  - id: references-to-components
+    title: References to Components
+  - id: children-undefined
+    title: this.props.children undefined

docs/_js/jsx-compiler.js

@@ -13,15 +13,38 @@ var HelloMessage = React.createClass({\n\
 React.renderComponent(<HelloMessage name=\"John\" />, mountNode);\
 ";
 
-var transformer = function(code) {
-  return JSXTransformer.transform(code).code;
+function transformer(harmony, code) {
+  return JSXTransformer.transform(code, {harmony: harmony}).code;
 }
+
+var CompilerPlayground = React.createClass({
+  getInitialState: function() {
+    return {harmony: false};
+  },
+  handleHarmonyChange: function(e) {
+    this.setState({harmony: e.target.checked});
+  },
+  render: function() {
+    return (
+      <div>
+        <ReactPlayground
+          codeText={HELLO_COMPONENT}
+          renderCode={true}
+          transformer={transformer.bind(null, this.state.harmony)}
+          showCompiledJSTab={false}
+        />
+        <label className="compiler-option">
+          <input
+            type="checkbox"
+            onChange={this.handleHarmonyChange}
+            checked={this.state.harmony} />{' '}
+          Enable ES6 transforms (<code>--harmony</code>)
+        </label>
+      </div>
+    );
+  },
+});
 React.renderComponent(
-  <ReactPlayground
-    codeText={HELLO_COMPONENT}
-    renderCode={true}
-    transformer={transformer}
-    showCompiledJSTab={false}
-  />,
+  <CompilerPlayground />,
   document.getElementById('jsxCompiler')
 );

docs/_js/live_editor.js

@@ -173,10 +173,11 @@ var ReactPlayground = React.createClass({
     this.executeCode();
   },
 
-  componentWillUpdate: function(nextProps, nextState) {
+  componentDidUpdate: function(prevProps, prevState) {
     // execute code only when the state's not being updated by switching tab
     // this avoids re-displaying the error, which comes after a certain delay
-    if (this.state.code !== nextState.code) {
+    if (this.props.transformer !== prevProps.transformer ||
+        this.state.code !== prevState.code) {
       this.executeCode();
     }
   },

docs/_layouts/default.html

@@ -6,12 +6,12 @@
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
   <title>React | {{ page.title }}</title>
   <meta name="viewport" content="width=device-width">
-  <meta property="og:title" content="React | {{ page.title }}" />
-  <meta property="og:type" content="website" />
-  <meta property="og:url" content="http://facebook.github.io/react{{ page.url }}" />
-  <meta property="og:image" content="http://facebook.github.io/react/img/logo_og.png" />
-  <meta property="og:description" content="A JavaScript library for building user interfaces" />
-  <meta property="fb:app_id" content="623268441017527" />
+  <meta property="og:title" content="React | {{ page.title }}">
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="http://facebook.github.io/react{{ page.url }}">
+  <meta property="og:image" content="http://facebook.github.io/react/img/logo_og.png">
+  <meta property="og:description" content="A JavaScript library for building user interfaces">
+  <meta property="fb:app_id" content="623268441017527">
 
   <link rel="shortcut icon" href="/react/favicon.ico">
   <link rel="alternate" type="application/rss+xml" title="{{ site.name }}" href="{{ site.url }}{{ site.baseurl }}/feed.xml">
@@ -30,7 +30,7 @@
   <![endif]-->
   <script type="text/javascript" src="/react/js/codemirror.js"></script>
   <script type="text/javascript" src="/react/js/javascript.js"></script>
-  <script type="text/javascript" src="/react/js/react.min.js"></script>
+  <script type="text/javascript" src="/react/js/react.js"></script>
   <script type="text/javascript" src="/react/js/JSXTransformer.js"></script>
   <script type="text/javascript" src="/react/js/live_editor.js"></script>
   <script type="text/javascript" src="/react/js/showdown.js"></script>

docs/_layouts/docs.html

@@ -7,8 +7,12 @@ sectionid: docs
   {% include nav_docs.html %}
 
   <div class="inner-content">
-    <h1>{{ page.title }}</h1>
+    <h1>
+      {{ page.title }}
+      <a class="edit-page-link" href="https://github.com/facebook/react/tree/master/docs/{{ page.path }}" target="_blank">Edit on GitHub</a>
+    </h1>
     <div class="subHeader">{{ page.description }}</div>
+
     {{ content }}
 
     <div class="docs-prevnext">
@@ -19,7 +23,5 @@ sectionid: docs
         <a class="docs-next" href="/react/docs/{{ page.next }}">Next &rarr;</a>
       {% endif %}
     </div>
-
-    <div class="fb-comments" data-width="650" data-num-posts="10" data-href="{{ site.url }}{{ site.baseurl }}{{ page.url }}"></div>
   </div>
 </section>

docs/_layouts/post.html

@@ -16,6 +16,5 @@ sectionid: blog
     </div>
 
     <div class="fb-like" data-send="true" data-width="650" data-show-faces="false"></div>
-    <div class="fb-comments" data-width="650" data-num-posts="10" data-href="{{ site.url }}{{ site.baseurl }}{{ page.url }}"></div>
   </div>
 </section>

docs/_layouts/tips.html

@@ -19,7 +19,5 @@ sectionid: tips
         <a class="docs-next" href="/react/tips/{{ page.next }}">Next &rarr;</a>
       {% endif %}
     </div>
-
-    <div class="fb-comments" data-width="650" data-num-posts="10" data-href="{{ site.url }}{{ site.baseurl }}{{ page.url }}"></div>
   </div>
 </section>

docs/_posts/2013-06-05-why-react.md

@@ -75,7 +75,7 @@ some pretty cool things with it:
 - We've built internal prototypes that run React apps in a web worker and use
   React to drive **native iOS views** via an Objective-C bridge.
 - You can run React
-  [on the server](http://github.com/petehunt/react-server-rendering)
+  [on the server](http://github.com/petehunt/react-server-rendering-example)
   for SEO, performance, code sharing and overall flexibility.
 - Events behave in a consistent, standards-compliant way in all browsers
   (including IE8) and automatically use

docs/_posts/2014-03-14-community-roundup-18.md

@@ -22,7 +22,7 @@ We're looking forward to part 2!
 
 ## React vs. async DOM manipulation
 
-Eliseu Monar ([@eliseumds](https://twitter.com/eliseumds))'s post "[ReactJS vs async concurrent rendering](http://eliseu.tk/post/77843550010/vitalbox-pchr-reactjs-vs-async-concurrent-rendering)" is a great example of how React quite literally renders a whole array of common web development work(arounds) obsolete.
+Eliseu Monar ([@eliseumds](https://twitter.com/eliseumds))'s post "[ReactJS vs async concurrent rendering](http://eliseumds.tumblr.com/post/77843550010/vitalbox-pchr-reactjs-vs-async-concurrent-rendering)" is a great example of how React quite literally renders a whole array of common web development work(arounds) obsolete.
 
 
 

docs/_posts/2014-03-19-react-v0.10-rc1.md

@@ -8,13 +8,13 @@ author: Paul O’Shannessy
 
 The release candidate is available for download from the CDN:
 
-* **React**
-  Dev build with warnings: <http://fb.me/react-0.10.0-rc1.js>
-  Minified build for production: <http://fb.me/react-0.10.0-rc1.min.js>
-* **React with Add-Ons**
-  Dev build with warnings: <http://fb.me/react-with-addons-0.10.0-rc1.js>
-  Minified build for production: <http://fb.me/react-with-addons-0.10.0-rc1.min.js>
-* **In-Browser JSX transformer**
+* **React**  
+  Dev build with warnings: <http://fb.me/react-0.10.0-rc1.js>  
+  Minified build for production: <http://fb.me/react-0.10.0-rc1.min.js>  
+* **React with Add-Ons**  
+  Dev build with warnings: <http://fb.me/react-with-addons-0.10.0-rc1.js>  
+  Minified build for production: <http://fb.me/react-with-addons-0.10.0-rc1.min.js>  
+* **In-Browser JSX transformer**  
   <http://fb.me/JSXTransformer-0.10.0-rc1.js>
 
 We've also published version `0.10.0-rc1` of the `react` and `react-tools` packages on npm and the `react` package on bower.
@@ -53,9 +53,10 @@ The plan for v0.11 is that we will go fully to "descriptors". Method calls on th
 ### React Core
 
 #### New Features
-* Made it possible to server render without React-related markup (`data-reactid`, `data-react-checksum`) - `React.renderComponentToStaticMarkup`
+* Added warnings to help migrate towards descriptors
+* Made it possible to server render without React-related markup (`data-reactid`, `data-react-checksum`). This DOM will not be mountable by React. [Read the docs for `React.renderComponentToStaticMarkup`](/react/docs/top-level-api.html#react.rendercomponenttostaticmarkup)
 * Added support for more attributes:
-  * `srcSet` for `<img>` to images at different pixel ratios
+  * `srcSet` for `<img>` to specify images at different pixel ratios
   * `textAnchor` for SVG
 
 #### Bug Fixes
@@ -65,7 +66,7 @@ The plan for v0.11 is that we will go fully to "descriptors". Method calls on th
 
 ### Addons
 
-* `update` function to deal with immutable data.
+* `update` function to deal with immutable data. [Read the docs](/react/docs/update.html)
 
 ### react-tools
 * Added an option argument to `transform` function. The only option supported is `harmony`, which behaves the same as `jsx --harmony` on the command line. This uses the ES6 transforms from [jstransform](https://github.com/facebook/jstransform).

docs/_posts/2014-03-21-react-v0.10.md

@@ -0,0 +1,73 @@
+---
+title: React v0.10
+layout: post
+author: Paul O’Shannessy
+---
+
+Hot on the heels of the [release candidate earlier this week](/react/blog/2014/03/19/react-v0.10-rc1.html), we're ready to call v0.10 done. The only major issue we discovered had to do with the `react-tools` package, which has been updated. We've copied over the changelog from the RC with some small clarifying changes.
+
+The release is available for download from the CDN:
+
+* **React**  
+  Dev build with warnings: <http://fb.me/react-0.10.0.js>  
+  Minified build for production: <http://fb.me/react-0.10.0.min.js>  
+* **React with Add-Ons**  
+  Dev build with warnings: <http://fb.me/react-with-addons-0.10.0.js>  
+  Minified build for production: <http://fb.me/react-with-addons-0.10.0.min.js>  
+* **In-Browser JSX transformer**  
+  <http://fb.me/JSXTransformer-0.10.0.js>
+
+We've also published version `0.10.0` of the `react` and `react-tools` packages on npm and the `react` package on bower.
+
+Please try these builds out and [file an issue on GitHub](https://github.com/facebook/react/issues/new) if you see anything awry.
+
+## Clone On Mount
+
+The main purpose of this release is to provide a smooth upgrade path as we evolve some of the implementation of core. In v0.9 we started warning in cases where you called methods on unmounted components. This is part of an effort to enforce the idea that the return value of a component (`React.DOM.div()`, `MyComponent()`) is in fact not a reference to the component instance React uses in the virtual DOM. The return value is instead a light-weight object that React knows how to use. Since the return value currently is a reference to the same object React uses internally, we need to make this transition in stages as many people have come to depend on this implementation detail.
+
+In 0.10, we’re adding more warnings to catch a similar set of patterns. When a component is mounted we clone it and use that object for our internal representation. This allows us to capture calls you think you’re making to a mounted component. We’ll forward them on to the right object, but also warn you that this is breaking. See “Access to the Mounted Instance” on [this page](http://fb.me/react-warning-descriptors). Most of the time you can solve your pattern by using refs.
+
+Storing a reference to your top level component is a pattern touched upon on that page, but another examples that demonstrates what we see a lot of:
+
+```js
+// This is a common pattern. However instance here really refers to a
+// "descriptor", not necessarily the mounted instance.
+var instance = <MyComponent/>;
+React.renderComponent(instance);
+// ...
+instance.setProps(...);
+
+// The change here is very simple. The return value of renderComponent will be
+// the mounted instance.
+var instance = React.renderComponent(<MyComponent/>)
+// ...
+instance.setProps(...);
+```
+
+These warnings and method forwarding are only enabled in the development build. The production builds continue to work as they did in v0.9. We strongly encourage you to use the development builds to catch these warnings and fix the call sites.
+
+The plan for v0.11 is that we will go fully to "descriptors". Method calls on the return value of `MyComponent()` will fail hard.
+
+## Changelog
+
+### React Core
+
+#### New Features
+* Added warnings to help migrate towards descriptors
+* Made it possible to server render without React-related markup (`data-reactid`, `data-react-checksum`). This DOM will not be mountable by React. [Read the docs for `React.renderComponentToStaticMarkup`](/react/docs/top-level-api.html#react.rendercomponenttostaticmarkup)
+* Added support for more attributes:
+  * `srcSet` for `<img>` to specify images at different pixel ratios
+  * `textAnchor` for SVG
+
+#### Bug Fixes
+* Ensure all void elements don’t insert a closing tag into the markup.
+* Ensure `className={false}` behaves consistently
+* Ensure `this.refs` is defined, even if no refs are specified.
+
+### Addons
+
+* `update` function to deal with immutable data. [Read the docs](/react/docs/update.html)
+
+### react-tools
+* Added an option argument to `transform` function. The only option supported is `harmony`, which behaves the same as `jsx --harmony` on the command line. This uses the ES6 transforms from [jstransform](https://github.com/facebook/jstransform).
+

docs/_posts/2014-03-28-the-road-to-1.0.md

@@ -0,0 +1,57 @@
+---
+title: The Road to 1.0
+layout: post
+author: Paul O'Shannessy
+---
+
+When we launched React last spring, we purposefully decided not to call it 1.0. It was production ready, but we had plans to evolve APIs and behavior as we saw how people were using React, both internally and externally. We've learned a lot over the past 9 months and we've thought a lot about what 1.0 will mean for React. A couple weeks ago, I outlined [several projects][projects] that we have planned to take us to 1.0 and beyond. Today I'm writing a bit more about them to give our users a better insight into our plans.
+
+Our primary goal with 1.0 is to clarify our messaging and converge on an API that is aligned with our goals. In order to do that, we want to clean up bad patterns we've seen in use and really help enable developers write good code.
+
+## Descriptors
+
+The first part of this is what we're calling "descriptors". I talked about this briefly in our [v0.10 announcements][v0.10]. The goal here is to separate our virtual DOM representation from our use of it. Simply, this means the return value of a component (e.g. `React.DOM.div()`, `MyComponent()`) will be a simple object containing the information React needs to render. Currently the object returned is actually linked to React's internal representation of the component and even directly to the DOM element. This has enabled some bad patterns that are quite contrary to how we want people to use React. That's our failure.
+
+We added some warnings in v0.9 to start migrating some of these bad patterns. With v0.10 we'll catch more. You'll see more on this soon as we expect to ship v0.11 with descriptors.
+
+## API Cleanup
+
+This is really connected to everything. We want to keep the API as simple as possible and help developers [fall into the pit of success][pitofsuccess]. Enabling bad patterns with bad APIs is not success.
+
+## ES6
+
+Before we even launched React publicly, members of the team were talking about how we could leverage ES6, namely classes, to improve the experience of creating React components. Calling `React.createClass(...)` isn't great. We don't quite have the right answer here yet, but we're close. We want to make sure we make this as simple as possible. It could look like this:
+
+```js
+class MyComponent extends React.Component {
+  render() {
+    ...
+  }
+}
+```
+
+There are other features of ES6 we're already using in core. I'm sure we'll see more of that. The `jsx` executable we ship with `react-tools` already supports transforming many parts of ES6 into code that will run on older browsers.
+
+## Context
+
+While we haven't documented `context`, it exists in some form in React already. It exists as a way to pass values through a tree without having to use props at every single point. We've seen this need crop up time and time again, so we want to make this as easy as possible. It's use has performance tradeoffs, and there are known weaknesses in our implementation, so we want to make sure this is a solid feature.
+
+## Addons
+
+As you may know, we ship a separate build of React with some extra features we called "addons". While this has served us fine, it's not great for our users. It's made testing harder, but also results in more cache misses for people using a CDN. The problem we face is that many of these "addons" need access to parts of React that we don't expose publicly. Our goal is to ship each addon on its own and let each hook into React as needed. This would also allow others to write and distribute "addons".
+
+## Browser Support
+
+As much as we'd all like to stop supporting older browsers, it's not always possible. Facebook still supports IE8. While React won't support IE8 forever, our goal is to have 1.0 support IE8. Hopefully we can continue to abstract some of these rough parts.
+
+## Animations
+
+Finding a way to define animations in a declarative way is a hard problem. We've been exploring the space for a long time. We've introduced some half-measures to alleviate some use cases, but the larger problem remains. While we'd like to make this a part of 1.0, realistically we don't think we'll have a good solution in place.
+
+## Miscellaneous
+
+There are several other things I listed on [our projects page][projects] that we're tracking. Some of them are internals and have no obvious outward effect (improve tests, repo separation, updated test runner). I encourage you to take a look.
+
+[v0.10]: http://facebook.github.io/react/blog/2014/03/21/react-v0.10.html
+[pitofsuccess]: http://blog.codinghorror.com/falling-into-the-pit-of-success/
+[projects]: https://github.com/facebook/react/wiki/Projects

docs/_posts/2014-04-04-reactnet.md

@@ -0,0 +1,38 @@
+---
+title: "Use React and JSX in ASP.NET MVC"
+layout: post
+author: Daniel Lo Nigro
+---
+
+Today we're happy to announce the initial release of
+[ReactJS.NET](http://reactjs.net/), which makes it easier to use React and JSX
+in .NET applications, focusing specifically on ASP.NET MVC web applications.
+It has several purposes:
+
+ - On-the-fly JSX to JavaScript compilation. Simply reference JSX files and they
+   will be compiled and cached server-side.
+
+   ```html
+   <script src="@Url.Content("/Scripts/HelloWorld.jsx")"></script>
+   ```
+ - JSX to JavaScript compilation via popular minification/combination libraries
+   (Cassette and ASP.NET Bundling and Minification). This is suggested for
+   production websites.
+ - Server-side component rendering to make your initial render super fast.
+
+Even though we are focusing on ASP.NET MVC, ReactJS.NET can also be used in
+Web Forms applications as well as non-web applications (for example, in build
+scripts). ReactJS.NET currently only works on Microsoft .NET but we are working
+on support for Linux and Mac OS X via Mono as well.
+
+Installation
+------------
+ReactJS.NET is packaged in NuGet. Simply run `Install-Package React.Mvc4` in the
+package manager console or search NuGet for "React" to install it.
+[See the documentation](http://reactjs.net/docs) for more information. The
+GitHub project contains
+[a sample website](https://github.com/reactjs/React.NET/tree/master/src/React.Sample.Mvc4)
+demonstrating all of the features.
+
+Let us know what you think, and feel free to send through any feedback and
+report bugs [on GitHub](https://github.com/reactjs/React.NET).

docs/_posts/2014-05-06-flux.md

@@ -0,0 +1,17 @@
+---
+title: "Flux: An Application Architecture for React"
+layout: post
+author: Bill Fisher and Jing Chen
+---
+
+We recently spoke at one of f8's breakout session about Flux, a data flow architecture that works well with React.  Check out the video here:
+
+<figure><iframe width="560" height="315" src="//www.youtube.com/embed/nYkdrAPrdcw?list=PLb0IAmt7-GS188xDYE-u1ShQmFFGbrk0v&start=621" frameborder="0" allowfullscreen></iframe></figure>
+
+To summarize, Flux works well for us because the single directional data flow makes it easy to understand and modify an application as it becomes more complicated. We found that two-way data bindings lead to cascading updates, where changing one data model led to another data model updating, making it very difficult to predict what would change as the result of a single user interaction.
+
+In Flux, the Dispatcher is a singleton that directs the flow of data and ensures that updates do not cascade. As an application grows, the Dispatcher becomes more vital, as it can also manage dependencies between stores by invoking the registered callbacks in a specific order.
+
+When a user interacts with a React view, the view sends an action (usually represented as a JavaScript object with some fields) through the dispatcher, which notifies the various stores that hold the application's data and business logic. When the stores change state, they notify the views that something has updated. This works especially well with React's declarative model, which allows the stores to send updates without specifying how to transition views between states.
+
+Flux is more of a pattern than a formal framework, so you can start using Flux immediately without a lot of new code. An [example of this architecture](https://github.com/facebook/react/tree/master/examples/todomvc-flux) is available, along with more [detailed documentation](http://facebook.github.io/react/docs/flux-overview.html) and a [tutorial](http://facebook.github.io/react/docs/flux-todo-list.html). Look for more examples to come in the future.

docs/_posts/2014-05-29-one-year-of-open-source-react.md

@@ -0,0 +1,15 @@
+---
+title: "One Year of Open-Source React"
+layout: post
+author: Cheng Lou
+---
+
+Today marks the one-year open-source anniversary of React.
+
+It’s been a crazy ride. 2.3k commits and 1.5k issues and pull requests later, we’re approaching version 1.0 and nearing 7k Github stars, with big names such as Khan Academy, New York Times, and Airbnb (and naturally, Facebook and Instagram) using React in production, and many more developers blogging their success stories with it. The [roadmap](http://facebook.github.io/react/blog/2014/03/28/the-road-to-1.0.html) gives a glimpse into the future of the library; exciting stuff lies ahead!
+
+Every success has its story. React was born out of our frustration at existing solutions for building UIs. When it was first suggested at Facebook, few people thought that functionally re-rendering everything and diffing the results could ever perform well. However, support grew after we built the first implementation and people wrote their first components. When we open-sourced React, the initial reception was [similarly skeptical](http://www.reddit.com/r/programming/comments/1fak87/react_facebooks_latest_javascript_client_library/). It challenges many pre-established conventions and received mostly disapproving first-impressions, intermingled with positive ones that often were votes of confidence in Facebook’s engineering capabilities. On an open, competitive platform such as the web, it's been hard to convince people to try React. [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html), in particular, filtered out a huge chunk of potential early adopters.
+
+Fast forward one year, React has strongly [grown in popularity](https://news.ycombinator.com/item?id=7489959). Special acknowledgments go to Khan Academy, the ClojureScript community, and established frameworks such as Ember and Angular for contributing to and debating on our work. We'd also like to thank all the [individual contributors](https://github.com/facebook/react/graphs/contributors) who have taken the time to help out over the past year. React, as a library and as a new paradigm on the web, wouldn't have gained as much traction without them. In the future, we will continue to try to set an example of what's possible to achieve when we rethink about current “best practices”.
+
+Here’s to another year!

docs/_posts/2014-06-27-community-roundup-19.md

@@ -0,0 +1,55 @@
+---
+title: "Community Round-up #19"
+layout: post
+author: Cheng Lou
+---
+
+## React Meetups!
+Ever wanted to find developers who also share the same interest in React than you? Recently, there has been a React Meetup in [San Francisco](http://www.meetup.com/ReactJS-San-Francisco/) (courtesy of [Telmate](http://www.telmate.com)), and one in [London](http://www.meetup.com/London-React-User-Group/) (courtesy of [Stuart Harris](http://www.meetup.com/London-React-User-Group/members/105837542/), [Cain Ullah](http://www.meetup.com/London-React-User-Group/members/15509971/) and [Zoe Merchant](http://www.meetup.com/London-React-User-Group/members/137058242/)). These two events have been big successes; a second one in London is [already planned](http://www.meetup.com/London-React-User-Group/events/191406572/).
+
+If you don't live near San Francisco or London, why not start one in your community?
+
+## Complementary Tools
+In case you haven't seen it, we've consolidated the tooling solution around React on [this wiki page](https://github.com/facebook/react/wiki/Complementary-Tools). Some of the notable recent entries include:
+
+- [Ryan Florence](https://github.com/rpflorence) and [Michael Jackson](https://github.com/mjackson)'s [react-nested-router](https://github.com/rpflorence/react-nested-router), which is a translation of the Ember router API to React.
+
+- [Stephen J. Collings](https://github.com/stevoland)'s [react-bootstrap](https://github.com/react-bootstrap/react-bootstrap), which wraps the popular framework with a bit of React goodness. The [website](http://react-bootstrap.github.io/components.html) features live-editable demos.
+
+- [Andrey Popp](https://github.com/andreypopp)'s [react-quickstart](https://github.com/andreypopp/react-quickstart), which gives you a quick template for server-side rendering and routing, among other features.
+
+These are some of the links that often pop up on the #reactjs IRC channel. If you made something that you think deserves to be shown on the wiki, feel free to add it!
+
+## React in Interesting Places
+
+The core concepts React themselves is something very valuable that the community is exploring and pushing further. A year ago, we wouldn't have imagined something like [Bruce Hauman](http://rigsomelight.com)'s [Flappy Bird ClojureScript port](http://rigsomelight.com/2014/05/01/interactive-programming-flappy-bird-clojurescript.html), whose interactive programming has been made possible through React:
+
+<iframe width="560" height="315" src="//www.youtube.com/embed/KZjFVdU8VLI" frameborder="0" allowfullscreen></iframe>
+
+And don't forget [Pete Hunt](https://github.com/petehunt)'s Wolfenstein 3D rendering engine in React ([source code](https://github.com/petehunt/wolfenstein3D-react/blob/master/js/renderer.js#L183)). While it's nearly a year old, it's still a nice demo.
+
+[![](/react/img/blog/wolfenstein_react.png)](http://www.petehunt.net/wolfenstein3D-react/wolf3d.html)
+
+Give us a shoutout on IRC or [React Google Groups](https://groups.google.com/forum/#!forum/reactjs) if you've used React in some Interesting places.
+
+## Even More People Using React
+
+### Prismatic
+[Prismatic](http://getprismatic.com/home) recently shrank their codebase fivefold with the help of React and its popular ClojureScript wrapper, [Om](https://github.com/swannodette/om). They detailed their very positive experience [here](http://blog.getprismatic.com/om-sweet-om-high-functional-frontend-engineering-with-clojurescript-and-react/).
+
+> Finally, the state is normalized: each piece of information is represented in a single place. Since React ensures consistency between the DOM and the application data, the programmer can focus on ensuring that the state properly stays up to date in response to user input. If the application state is normalized, then this consistency is guaranteed by definition, completely avoiding the possibility of an entire class of common bugs.
+
+### Adobe Brackets
+[Kevin Dangoor](http://www.kevindangoor.com) works on [Brackets](http://brackets.io/?lang=en), the open-source code editor. After writing [his first impression on React](http://www.kevindangoor.com/2014/05/simplifying-code-with-react/), he followed up with another insightful [article](http://www.kevindangoor.com/2014/05/react-in-brackets/) on how to gradually make the code transition, how to preserve the editor's good parts, and how to tune Brackets' tooling around JSX.
+
+> We don’t need to switch to React everywhere, all at once. It’s not a framework that imposes anything on the application structure. [...] Easy, iterative adoption is definitely something in React’s favor for us.
+
+### Storehouse
+[Storehouse](https://www.storehouse.co) (Apple Design Award 2014)'s web presence is build with React. Here's [an example story](https://www.storehouse.co/stories/y2ad-mexico-city-clouds). Congratulations on the award!
+
+### Vim Awesome
+[Vim Awesome](http://vimawesome.com), an open-source Vim plugins directory built on React, was just launched. Be sure to [check out the source code](https://github.com/divad12/vim-awesome) if you're curious to see an example of how to build a small single-page React app.
+
+## Random Tweets
+
+<blockquote class="twitter-tweet" lang="en"><p>Spent 12 hours so far with <a href="https://twitter.com/hashtag/reactjs?src=hash">#reactjs</a>. Spent another 2 wondering why we&#39;ve been doing JS frameworks wrong until now. React makes me happy.</p>&mdash; Paul Irwin (@paulirwin) <a href="https://twitter.com/paulirwin/statuses/481263947589242882">June 24, 2014</a></blockquote>

docs/_posts/2014-07-13-react-v0.11-rc1.md

@@ -0,0 +1,147 @@
+---
+title: React v0.11 RC
+layout: post
+author: Paul O’Shannessy
+---
+
+It's that time again… we're just about ready to ship a new React release! v0.11 includes a wide array of bug fixes and features. We highlighted some of the most important changes below, along with the full changelog.
+
+The release candidate is available for download from the CDN:
+
+* **React**  
+  Dev build with warnings: <http://fb.me/react-0.11.0-rc1.js>  
+  Minified build for production: <http://fb.me/react-0.11.0-rc1.min.js>  
+* **React with Add-Ons**  
+  Dev build with warnings: <http://fb.me/react-with-addons-0.11.0-rc1.js>  
+  Minified build for production: <http://fb.me/react-with-addons-0.11.0-rc1.min.js>  
+* **In-Browser JSX transformer**  
+  <http://fb.me/JSXTransformer-0.11.0-rc1.js>
+
+We've also published version `0.11.0-rc1` of the `react` and `react-tools` packages on npm and the `react` package on bower.
+
+Please try these builds out and [file an issue on GitHub](https://github.com/facebook/react/issues/new) if you see anything awry.
+
+
+# Blog Post
+
+## `getDefaultProps`
+
+Starting in React 0.11, `getDefaultProps()` is called only once when `React.createClass()` is called, instead of each time a component is rendered. This means that `getDefaultProps()` can no longer vary its return value based on `this.props` and any objects will be shared across all instances. This change improves performance and will make it possible in the future to do PropTypes checks earlier in the rendering process, allowing us to give better error messages.
+
+
+## Rendering to `null`
+
+Since React's release, people have been using work arounds to "render nothing". Usually this means returning an empty `<div/>` or `<span/>`. Some people even got clever and started returning `<noscript/>` to avoid extraneous DOM nodes. We finally provided a "blessed" solution that allows developers to writing meaningful code. Returning `null` in an explicit indication to React that you do not want anything rendered. Behind the scenes we make this work with a `<noscript>` element, though in the future we hope to not put anything in the document. In the mean time, `<noscript>` elements do not affect layout in any way, so you can feel safe using `null` today!
+
+```js
+// Before
+render: function() {
+  if (!this.state.visible) {
+    return <span/>;
+  }
+  // ...
+}
+
+// After
+render: function() {
+  if (!this.state.visible) {
+    return null;
+  }
+  // ...
+}
+```
+
+
+## JSX Namespacing
+
+Another feature request we've been hearing for a long time is the ability to have namespaces in JSX. Given that JSX is just JavaScript, we didn't want to use XML namespacing. Instead we opted for a standard JS approach: object property access. Instead of assigning variables to access components stored in an object (such as a component library), you can now use the component directly as `<Namespace.Component/>`.
+
+```js
+// Before
+var UI = require('UI');
+var UILayout = UI.Layout;
+var UIButton = UI.Button;
+var UILabel = UI.Label;
+
+render: function() {
+  return <UILayout><UIButton /><UILabel>text</UILabel></UILayout>;
+}
+
+// After
+var UI = require('UI');
+
+render: function() {
+  return <UI.Layout><UI.Button /><UI.Label>text</UI.Label></UI.Layout>;
+}
+```
+
+
+## Improved keyboard event normalization
+
+Keyboard events now contain a normalized `e.key` value according to the [DOM Level 3 Events spec](http://www.w3.org/TR/DOM-Level-3-Events/#keys-special), allowing you to write simpler key handling code that works in all browsers, such as:
+
+```js
+handleKeyDown: function(e) {
+  if (e.key === 'Enter') {
+    // Handle enter key
+  } else if (e.key === ' ') {
+    // Handle spacebar
+  } else if (e.key === 'ArrowLeft') {
+    // Handle left arrow
+  }
+},
+```
+
+Keyboard and mouse events also now include a normalized `e.getModifierState()` that works consistently across browsers.
+
+## Changelog
+
+### React Core
+
+#### Breaking Changes
+* `getDefaultProps()` is now called once per class and shared across all instances
+
+#### New Features
+* Rendering to `null`
+* Keyboard events include normalized `e.key` and `e.getModifierState()` properties
+* New normalized `onBeforeInput` event
+* `React.Children.count` has been added as a helper for counting the number of children
+
+#### Bug Fixes
+
+* Re-renders are batched in more cases
+* Events: `e.view` properly normalized
+* Added Support for more HTML attributes (`coords`, `crossOrigin`, `download`, `hrefLang`, `mediaGroup`, `muted`, `scrolling`, `shape`, `srcSet`, `start`, `useMap`)
+* Improved SVG support
+  * Changing `className` on a mounted SVG component now works correctly
+  * Added support for elements `mask` and `tspan`
+  * Added support for attributes `dx`, `dy`, `fillOpacity`, `fontFamily`, `fontSize`, `markerEnd`, `markerMid`, `markerStart`, `opacity`, `patternContentUnits`, `patternUnits`, `preserveAspectRatio`, `strokeDasharray`, `strokeOpacity`
+* CSS property names with vendor prefixes (`Webkit`, `ms`, `Moz`, `O`) are now handled properly
+* Duplicate keys no longer cause a hard error; now a warning is logged (and only one of the children with the same key is shown)
+* `img` event listeners are now unbound properly, preventing the error "Two valid but unequal nodes with the same `data-reactid`"
+* Added explicit warning when missing polyfills
+
+### React With Addons
+* PureRenderMixin
+* Perf: a new set of tools to help with performance analysis
+* Update: New `$apply` command to transform values
+* TransitionGroup bug fixes with null elements, Android
+
+### React NPM Module
+* Now includes the pre-built packages under `dist/`.
+* `envify` is properly listed as a dependency instead of a peer dependency
+
+### JSX
+* Added support for namespaces, eg `<Components.Checkbox />`
+* JSXTransformer
+  * Enable the same `harmony` features available in the command line with `<script type="text/jsx;harmony=true">`
+  * Scripts are downloaded in parallel for more speed. They are still executed in order (as you would expect with normal script tags)
+  * Fixed a bug preventing sourcemaps from working in Firefox
+
+### React Tools Module
+* Improved readme with usage and API information
+* Improved ES6 transforms available with `--harmony` option
+* Added `--source-map-inline` option to the `jsx` executable
+* New `transformWithDetails` API which gives access to the raw sourcemap data
+
+

docs/acknowledgements.md

@@ -8,6 +8,8 @@ We'd like to thank all of our contributors:
 
 <div class="three-column">
   <ul>
+    <li>Adam Krebs</li>
+    <li>Adam Solove</li>
     <li>Alan deLevie</li>
     <li>Alex Zelenskiy</li>
     <li>Alexander Solovyov</li>
@@ -15,46 +17,74 @@ We'd like to thank all of our contributors:
     <li>Andrew Davey</li>
     <li>Andrew Zich</li>
     <li>Andrey Popp</li>
+    <li>Anthony van der Hoorn</li>
     <li>Ayman Osman</li>
     <li>Ben Alpert</li>
     <li>Ben Newman</li>
     <li>Ben Ripkens</li>
+    <li>Bill Fisher</li>
     <li>Bob Eagan</li>
+    <li>Bojan Mihelac</li>
+    <li>Brandon Bloom</li>
     <li>Brian Cooke</li>
     <li>Brian Kim</li>
+    <li>Brian Reavis</li>
     <li>Brian Rue</li>
     <li>Cam Spiers</li>
+    <li>Cassus Adam Banko</li>
     <li>Cat Chen</li>
     <li>Cheng Lou</li>
     <li>Christian Roman</li>
     <li>Christoph Pojer</li>
+    <li>Christopher Monsanto</li>
     <li>Clay Allsopp</li>
     <li>Connor McSheffrey</li>
     <li>Dan Schafer</li>
     <li>Daniel Gasienica</li>
     <li>Daniel Lo Nigro</li>
     <li>Daniel Miladinov</li>
+    <li>Daniel Schonfeld</li>
     <li>Danny Ben-David</li>
+    <li>Daryl Lau</li>
     <li>David Hellsing</li>
     <li>David Hu</li>
+    <li>Devon Blandin</li>
+    <li>Dmitry Mazuro</li>
     <li>Dustin Getz</li>
+    <li>Enguerran</li>
     <li>Eric Clemmons</li>
+    <li>Eric Florenzano</li>
     <li>Eric Schoffstall</li>
+    <li>Evan Coonrod</li>
     <li>Fabio M. Costa</li>
     <li>Felipe Oliveira Carvalho</li>
     <li>Felix Kling</li>
     <li>Fernando Correia</li>
-    <li>Greg Roodt</li>
+    <li>François-Xavier Bois</li>
+    <li>Fred Zhao</li>
+    <li>G Scott Olson</li>
+    <li>Geert Pasteels</li>
+    <li>Geert-Jan Brits</li>
+    <li>George A Sisco III</li>
+    <li>Gilbert</li>
+    <li>Greg Hurrell</li>
   </ul>
   <ul>
+    <li>Greg Roodt</li>
+    <li>Guangqiang Dong</li>
     <li>Guido Bouman</li>
     <li>Harry Hull</li>
+    <li>Harshad Sabne</li>
+    <li>Hendrik Swanepoel</li>
     <li>Hugo Jobling</li>
     <li>Ian Obermiller</li>
     <li>Ingvar Stepanyan</li>
+    <li>Irae Carvalho</li>
     <li>Isaac Salier-Hellendag</li>
     <li>Ivan Kozik</li>
+    <li>Jaime Mingo</li>
     <li>Jakub Malinowski</li>
+    <li>James Brantly</li>
     <li>James Ide</li>
     <li>Jamie Wong</li>
     <li>Jamison Dance</li>
@@ -63,38 +93,59 @@ We'd like to thank all of our contributors:
     <li>Jason Bonta</li>
     <li>Jason Trill</li>
     <li>Jean Lauliac</li>
+    <li>Jeff Barczewski</li>
+    <li>Jeff Carpenter</li>
     <li>Jeff Morrison</li>
+    <li>Jeff Welch</li>
     <li>Jeffrey Lin</li>
     <li>Jignesh Kakadiya</li>
+    <li>Jing Chen</li>
     <li>Johannes Baiter</li>
     <li>John Watson</li>
+    <li>Jon Beebe</li>
+    <li>Jonas Enlund</li>
     <li>Jonas Gebhardt</li>
     <li>Jonathan Hsu</li>
     <li>Jordan Walke</li>
+    <li>Josh Bassett</li>
     <li>Josh Duck</li>
+    <li>Josh Yudaken</li>
+    <li>Joshua Ma</li>
+    <li>Julen Ruiz Aizpuru</li>
     <li>Jun Wu</li>
+    <li>Juraj Dudak</li>
+    <li>Justin Jaffray</li>
+    <li>Karl Mikkelsen</li>
     <li>Keito Uchiyama</li>
     <li>Kit Randel</li>
     <li>Kunal Mehta</li>
+    <li>Kyle Mathews</li>
     <li>Laurence Rowe</li>
     <li>Levi McCallum</li>
+    <li>Lily</li>
     <li>Logan Allen</li>
     <li>Luigy Leon</li>
+    <li>Marcin Kwiatkowski</li>
+    <li>Marcin Szczepanski</li>
+    <li>Mariano Desanze</li>
     <li>Mark Richardson</li>
+  </ul>
+  <ul>
     <li>Marshall Roch</li>
     <li>Martin Andert</li>
     <li>Martin Konicek</li>
-  </ul>
-  <ul>
     <li>Mathieu M-Gosselin</li>
     <li>Matt Harrison</li>
+    <li>Matthew Dapena-Tretter</li>
     <li>Matti Nelimarkka</li>
     <li>Michal Srb</li>
     <li>Mouad Debbar</li>
     <li>Nadeesha Cabral</li>
+    <li>Nate Hunzaker</li>
     <li>Nicholas Bergson-Shilcock</li>
     <li>Nick Gavalas</li>
     <li>Nick Thompson</li>
+    <li>Niklas Boström</li>
     <li>Owen Coutts</li>
     <li>Pascal Hartig</li>
     <li>Paul O’Shannessy</li>
@@ -104,24 +155,42 @@ We'd like to thank all of our contributors:
     <li>Peter Cottle</li>
     <li>Petri Lievonen</li>
     <li>Pieter Vanderwerff</li>
+    <li>Rajiv Tirumalareddy</li>
+    <li>Randall Randall</li>
+    <li>Ray</li>
     <li>Richard D. Worth</li>
     <li>Richard Feldman</li>
     <li>Richard Livesey</li>
+    <li>Ryan Seddon</li>
+    <li>Sahat Yalkabov</li>
     <li>Sander Spies</li>
     <li>Sean Kinsey</li>
     <li>Sebastian Markbåge</li>
     <li>Shaun Trennery</li>
     <li>Simon Højberg</li>
+    <li>Stefan Dombrowski</li>
+    <li>Stephen Murphy</li>
     <li>Stoyan Stefanov</li>
     <li>Sundeep Malladi</li>
+    <li>Sven Helmberger</li>
     <li>Thomas Aylott</li>
+    <li>Thomas Boyt</li>
+    <li>Thomas Shaddox</li>
+    <li>Thomas Shafer</li>
     <li>Timothy Yung</li>
+    <li>Tom Haggie</li>
     <li>Tom Occhino</li>
+    <li>Ville Immonen</li>
     <li>Vjeux</li>
+    <li>Volkan Unsal</li>
+    <li>Wayne Larsen</li>
     <li>Wincent Colaiuta</li>
+    <li>Yuriy Dybskiy</li>
+    <li>Yuval Dekel</li>
     <li>Zach Bruggeman</li>
+    <li>davidxi</li>
     <li>imagentleman</li>
   </ul>
 </div>
 
-In addition, we're grateful to [Jeff Barczewski](https://github.com/jeffbski) for allowing us to use the `react` package name on npm.
+In addition, we're grateful to [Jeff Barczewski](https://github.com/jeffbski) for allowing us to use the [react](https://www.npmjs.org/package/react) package name on npm and to [Christopher Aue](http://christopheraue.net/) for letting us use the [reactjs.com](http://reactjs.com/) domain name and the [@reactjs](https://twitter.com/reactjs) username on Twitter.

docs/blog/index.html

@@ -20,7 +20,7 @@ sectionid: blog
 
     <div class="pagination">
       {% if paginator.previous_page %}
-        <a href="/react/{{ paginator.previous_page_path }}" class="previous">
+        <a href="/react{{ paginator.previous_page_path }}" class="previous">
           &laquo; Previous Page
         </a>
       {% endif %}

docs/docs/01-why-react.zh-CN.md

@@ -0,0 +1,33 @@
+---
+id: why-react-zh-CN
+title: 为什么使用 React?
+layout: docs
+permalink: why-react-zh-CN.html
+next: displaying-data.html
+---
+
+React 是一个 Facebook 和 Instagram 用来创建用户界面的 JavaScript 库。很人多认为 React 是 **[MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)** 中的 **V**（视图）。
+
+我们创造 React 是为了解决一个问题：**构建随着时间数据不断变化的大规模应用程序**。为了达到这个目标，React 采用下面两个主要的思想。
+
+### 简单
+
+仅仅只要表达出你的应用程序在任一个时间点应该长的样子，然后当底层的数据变了，React 会自动处理所有用户界面的更新。
+
+### 表达能力 (Declarative)
+
+当数据变化了，React 概念上是类似点击了更新的按钮，但仅会更新变化的部分。
+
+## 构建可组合的组件
+
+React 都是关于构建可复用的组件。事实上，通过 React 你*唯一*要做的事情就是构建组件。得益于其良好的封装性，组件使代码复用、测试和关注分离（separation of concerns）更加简单。
+
+## 给它5分钟的时间
+
+React挑战了很多传统的知识，第一眼看上去可能很多想法有点疯狂。当你阅读这篇指南，请[给它5分钟的时间](http://37signals.com/svn/posts/3124-give-it-five-minutes)；那些疯狂的想法已经帮助 Facebook 和 Instagram 从里到外创建了上千的组件了。
+
+## 了解更多
+
+你可以从这篇[博客](http://facebook.github.io/react/blog/2013/06/05/why-react.html)了解更多我们创造 React 的动机。
+
+

docs/docs/02.1-jsx-in-depth.md

@@ -161,10 +161,20 @@ var content = Container(null, window.isLoggedIn ? Nav(null) : Login(null));
 
 ### Comments
 
-It's easy to add comments within your JSX; they're just JS expressions:
+It's easy to add comments within your JSX; they're just JS expressions. You just need to be careful to put `{}` around the comments when you are within the children section of a tag.
 
 ```javascript
-var content = <Container>{/* this is a comment */}<Nav /></Container>;
+var content = (
+  <Nav>
+    {/* child comment, put {} around */}
+    <Person
+      /* multi
+         line
+         comment */
+      name={window.isLoggedIn ? window.name : ''} // end of line comment
+    />
+  </Nav>
+);
 ```
 
 

docs/docs/03-interactivity-and-dynamic-uis.md

@@ -43,7 +43,7 @@ React.renderComponent(
 
 With React you simply pass your event handler as a camelCased prop similar to how you'd do it in normal HTML. React ensures that all events behave identically in IE8 and above by implementing a synthetic event system. That is, React knows how to bubble and capture events according to the spec, and the events passed to your event handler are guaranteed to be consistent with [the W3C spec](http://www.w3.org/TR/DOM-Level-3-Events/), regardless of which browser you're using.
 
-If you'd like to use React on a touch device (i.e. a phone or tablet), simply call `React.initializeTouchEvents(true);` to turn them on.
+If you'd like to use React on a touch device such as a phone or tablet, simply call `React.initializeTouchEvents(true);` to enable touch event handling.
 
 
 ## Under the Hood: Autobinding and Event Delegation
@@ -80,7 +80,7 @@ A common pattern is to create several stateless components that just render data
 
 **State should contain data that a component's event handlers may change to trigger a UI update.** In real apps this data tends to be very small and JSON-serializable. When building a stateful component, think about the minimal possible representation of its state, and only store those properties in `this.state`. Inside of `render()` simply compute any other information you need based on this state. You'll find that thinking about and writing applications in this way tends to lead to the most correct application, since adding redundant or computed values to state means that you need to explicitly keep them in sync rather than rely on React computing them for you.
 
-## What *Shouldn't* Go in State?
+## What *Shouldn’t* Go in State?
 
 `this.state` should only contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:
 

docs/docs/05-reusable-components.md

@@ -51,23 +51,28 @@ React.createClass({
     // An array of a certain type
     optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number),
 
+    // An object with property values of a certain type
+    optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number),
+
     // An object taking on a particular shape
     optionalObjectWithShape: React.PropTypes.shape({
       color: React.PropTypes.string,
       fontSize: React.PropTypes.number
     }),
 
-    // You can chain any of the above with isRequired to make sure a warning is
-    // shown if the prop isn't provided.
+    // You can chain any of the above with `isRequired` to make sure a warning
+    // is shown if the prop isn't provided.
     requiredFunc: React.PropTypes.func.isRequired,
 
-    // An object of any kind
+    // A value of any data type
     requiredAny: React.PropTypes.any.isRequired,
 
-    // You can also specify a custom validator.
+    // You can also specify a custom validator. It should return an Error
+    // object if the validation fails. Don't `console.warn` or throw, as this
+    // won't work inside `oneOfType`.
     customProp: function(props, propName, componentName) {
       if (!/matchme/.test(props[propName])) {
-        console.warn('Validation failed!');
+        return new Error('Validation failed!');
       }
     }
   },

docs/docs/06-forms.md

@@ -9,6 +9,7 @@ next: working-with-the-browser.html
 
 Form components such as `<input>`, `<textarea>`, and `<option>` differ from other native components because they can be mutated via user interactions. These components provide interfaces that make it easier to manage forms in response to user interactions.
 
+For information on events on `<form>` see [Form Events](/react/docs/events.html#form-events).
 
 ## Interactive Props
 

docs/docs/07-working-with-the-browser.md

@@ -116,16 +116,20 @@ In addition to that philosophy, we've also taken the stance that we, as authors
 `es5-shim.js` from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim) provides the following that React needs:
 
 * `Array.isArray`
+* `Array.prototype.every`
 * `Array.prototype.forEach`
 * `Array.prototype.indexOf`
-* `Array.prototype.some`
+* `Array.prototype.map`
 * `Date.now`
 * `Function.prototype.bind`
 * `Object.keys`
+* `String.prototype.split`
+* `String.prototype.trim`
 
 `es5-sham.js`, also from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim), provides the following that React needs:
 
 * `Object.create`
+* `Object.freeze`
 
 The unminified build of React needs the following from [paulmillr's console-polyfill](https://github.com/paulmillr/console-polyfill).
 

docs/docs/07.1-more-about-refs.md

@@ -15,7 +15,7 @@ Consider the case when you wish to tell an `<input />` element (that exists with
     getInitialState: function() {
       return {userInput: ''};
     },
-    handleKeyUp: function(e) {
+    handleChange: function(e) {
       this.setState({userInput: e.target.value});
     },
     clearAndFocusInput: function() {
@@ -26,11 +26,11 @@ Consider the case when you wish to tell an `<input />` element (that exists with
       return (
         <div>
           <div onClick={this.clearAndFocusInput}>
-            Click To Focus and Reset
+            Click to Focus and Reset
           </div>
           <input
             value={this.state.userInput}
-            onKeyUp={this.handleKeyUp}
+            onChange={this.handleChange}
           />
         </div>
       );
@@ -72,17 +72,19 @@ React supports a very special property that you can attach to any component that
 
 It's as simple as:
 
-**1.** Assign a `ref` attribute to anything returned from `render` such as:
+1. Assign a `ref` attribute to anything returned from `render` such as:
 
-```html
-   <input ref="myInput" />
-```
+  ```html
+  <input ref="myInput" />
+  ```
 
-**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
+2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
 
-```javascript
+  ```javascript
   this.refs.myInput
-```
+  ```
+
+  You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`.
 
 ## Completing the Example
 
@@ -91,23 +93,26 @@ It's as simple as:
     getInitialState: function() {
       return {userInput: ''};
     },
-    handleKeyUp: function(e) {
+    handleChange: function(e) {
       this.setState({userInput: e.target.value});
     },
     clearAndFocusInput: function() {
-      this.setState({userInput: ''}); // Clear the input
-      this.refs.theInput.getDOMNode().focus();   // Boom! Focused!
+      // Clear the input
+      this.setState({userInput: ''}, function() {
+        // This code executes after the component is re-rendered
+        this.refs.theInput.getDOMNode().focus();   // Boom! Focused!
+      });
     },
     render: function() {
       return (
         <div>
           <div onClick={this.clearAndFocusInput}>
-            Click To Focus and Reset
+            Click to Focus and Reset
           </div>
           <input
             ref="theInput"
             value={this.state.userInput}
-            onKeyUp={this.handleKeyUp}
+            onChange={this.handleChange}
           />
         </div>
       );
@@ -132,4 +137,4 @@ Refs are a great way to send a message to a particular child instance in a way t
 
 - *Never* access refs inside of any component's render method - or while any component's render method is even running anywhere in the call stack.
 - If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.
-- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.
+- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" – instead, the data flow will usually accomplish your goal.

docs/docs/08-tooling-integration.md

@@ -38,14 +38,4 @@ If you have [npm](http://npmjs.org/), you can simply run `npm install -g react-t
 
 ### Helpful Open-Source Projects
 
-The open-source community has built tools that integrate JSX with several build systems. See [JSX integrations](/react/docs/complementary-tools.html#jsx-integrations) for the full list.
-
-
-### Syntax Highlighting & Linting
-
-* Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
-  * [JSX syntax highlighting](https://github.com/yungsters/sublime/blob/master/tmLanguage/JavaScript%20(JSX\).tmLanguage) is available for Sublime Text and other editors
-    that support `*.tmLanguage`.
-  * [web-mode.el](http://web-mode.org) is an autonomous emacs major mode that indents and highlights JSX
-* Linting provides accurate line numbers after compiling without sourcemaps.
-* Elements use standard scoping so linters can find usage of out-of-scope components.
+The open-source community has built tools that integrate JSX with several editors and build systems. See [JSX integrations](https://github.com/facebook/react/wiki/Complementary-Tools#jsx-integrations) for the full list.

docs/docs/09-addons.md

@@ -11,7 +11,9 @@ next: animation.html
 
 - [`ReactTransitions`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal.
 - [`ReactLink`](two-way-binding-helpers.html), to simplify the coordination between user's form input data and and the component's state.
-- [`classSet`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly.
+- [`classSet()`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly.
 - [`ReactTestUtils`](test-utils.html), simple helpers for writing test cases (unminified build only).
+- [`cloneWithProps()`](clone-with-props.html), to make shallow copies of React components and change their props.
+- [`update()`](update.html), a helper function that makes dealing with immutable data in JavaScript easier.
 
 To get the add-ons, use `react-with-addons.js` (and its minified counterpart) rather than the common `react.js`.

docs/docs/09.1-animation.md

@@ -17,7 +17,7 @@ React provides a `ReactTransitionGroup` addon component as a low-level API for a
 
 `ReactCSSTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.
 
-```javascript{22-24}
+```javascript{30-32}
 /** @jsx React.DOM */
 
 var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup;
@@ -33,7 +33,7 @@ var TodoList = React.createClass({
   },
   handleRemove: function(i) {
     var newItems = this.state.items;
-    newItems.splice(i, 1)
+    newItems.splice(i, 1);
     this.setState({items: newItems});
   },
   render: function() {
@@ -46,7 +46,7 @@ var TodoList = React.createClass({
     }.bind(this));
     return (
       <div>
-        <div><button onClick={this.handleAdd} /></div>
+        <button onClick={this.handleAdd}>Add Item</button>
         <ReactCSSTransitionGroup transitionName="example">
           {items}
         </ReactCSSTransitionGroup>
@@ -88,6 +88,10 @@ You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keep
 
 You can disable animating `enter` or `leave` animations if you want. For example, sometimes you may want an `enter` animation and no `leave` animation, but `ReactCSSTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactCSSTransitionGroup` to disable these animations.
 
+> Note:
+>
+> When using `ReactCSSTransitionGroup`, there's no way for your components to be notified when a transition has ended or to perform any more complex logic around animation. If you want more fine-grained control, you can use the lower-level `ReactTransitionGroup` API which provides the hooks you need to do custom transitions.
+
 ## Low-level API: `ReactTransitionGroup`
 
 `ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.

docs/docs/09.4-test-utils.md

@@ -7,22 +7,23 @@ prev: class-name-manipulation.html
 next: clone-with-props.html
 ---
 
-`React.addons.TestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jasmine](http://pivotal.github.io/jasmine/) with [jsdom](https://github.com/tmpvar/jsdom)).
+`React.addons.TestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jest](http://facebook.github.io/jest/)).
 
 ### Simulate
 
 ```javascript
-Simulate.{eventName}({ReactComponent|DOMElement} element, object eventData)
+Simulate.{eventName}(DOMElement element, object eventData)
 ```
 
-Simulate an event dispatch on a React component instance or browser DOM node with optional `eventData` event data. **This is possibly the single most useful utility in `ReactTestUtils`.**
+Simulate an event dispatch on a DOM node with optional `eventData` event data. **This is possibly the single most useful utility in `ReactTestUtils`.**
 
 Example usage:
 
 ```javascript
-React.addons.TestUtils.Simulate.click(myComponent);
-React.addons.TestUtils.Simulate.change(myComponent);
-React.addons.TestUtils.Simulate.keydown(myComponent, {key: "Enter"});
+var node = this.refs.input.getDOMNode();
+React.addons.TestUtils.Simulate.click(node);
+React.addons.TestUtils.Simulate.change(node);
+React.addons.TestUtils.Simulate.keyDown(node, {key: "Enter"});
 ```
 
 `Simulate` has a method for every event that React understands.
@@ -94,7 +95,7 @@ Traverse all components in `tree` and accumulate all components where `test(comp
 ### scryRenderedDOMComponentsWithClass
 
 ```javascript
-array scryRenderedDOMComponentsWithClass(ReactCompoennt tree, string className)
+array scryRenderedDOMComponentsWithClass(ReactComponent tree, string className)
 ```
 
 Finds all instance of components in the rendered tree that are DOM components with the class name matching `className`.

docs/docs/09.5-clone-with-props.md

@@ -4,6 +4,7 @@ title: Cloning Components
 layout: docs
 permalink: clone-with-props.html
 prev: test-utils.html
+next: update.html
 ---
 
 In rare situations a component may want to change the props of a component that it doesn't own (like changing the `className` of a component passed as `this.props.children`). Other times it may want to make multiple copies of a component passed to it. `cloneWithProps()` makes this possible.

docs/docs/09.6-update.md

@@ -0,0 +1,101 @@
+---
+id: update
+title: Immutability Helpers
+layout: docs
+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 overriden. 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 `array()` 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}
+```

docs/docs/09.7-pure-render-mixin.md

@@ -0,0 +1,31 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+layout: docs
+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.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.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".

docs/docs/09.8-perf.md

@@ -0,0 +1,70 @@
+---
+id: perf
+title: Performance Tools
+layout: docs
+permalink: perf.html
+prev: pure-render-mixin.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
+
+### `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
+}
+```

docs/docs/complementary-tools.md

@@ -7,54 +7,4 @@ prev: videos.html
 next: examples.html
 ---
 
-React is a small library that does one thing well. Here's a list of tools we've found that work really well with React when building applications.
-
-If you want your project on this list, or think one of these projects should be removed, [open an issue on GitHub](https://github.com/facebook/react/issues/new).
-
-### JSX integrations
-
-  * **[jsxhint](https://npmjs.org/package/jsxhint)** [JSHint](http://jshint.com/) (linting) support.
-  * **[reactify](https://npmjs.org/package/reactify)** [Browserify](http://browserify.org/) transform.
-  * **[node-jsx](https://npmjs.org/package/node-jsx)** Native [Node](http://nodejs.org/) support.
-  * **[jsx-loader](https://npmjs.org/package/jsx-loader)** Loader for [webpack](http://webpack.github.io/).
-  * **[grunt-react](https://npmjs.org/package/grunt-react)** [GruntJS](http://gruntjs.com/) task.
-  * **[gulp-react](https://npmjs.org/package/gulp-react)** [GulpJS](http://gulpjs.com/) plugin.
-  * **[jsx-requirejs-plugin](https://github.com/philix/jsx-requirejs-plugin)** [RequireJS](http://requirejs.org/) plugin.
-  * **[react-meteor](https://github.com/benjamn/react-meteor)** [Meteor](http://www.meteor.com/) plugin.
-  * **[pyReact](https://github.com/facebook/react-python)** [Python](http://www.python.org/) bridge to JSX.
-  * **[react-rails](https://github.com/facebook/react-rails)** Ruby gem for using JSX with [Ruby on Rails](http://rubyonrails.org/).
-
-### Full-stack starter kits
-
-  * **[react-quickstart](https://github.com/andreypopp/react-quickstart)** Quick-start template for `express`, `browserify`, `react-router-component` and `react-async` (**includes "isomorphic" server rendering**).
-  * **[generator-react-webpack](https://github.com/newtriks/generator-react-webpack)** [Yeoman](http://yeoman.io/) generator for React and Webpack.
-  * **[Genesis Skeleton](http://genesis-skeleton.com/)** Modern, opinionated, full-stack starter kit for rapid, streamlined application development (supports React).
-  * **[react-starter-template](https://github.com/johnthethird/react-starter-template)** Starter template with Gulp, Webpack and Bootstrap.
-  * **[react-brunch](https://npmjs.org/package/react-brunch)** [Brunch](http://brunch.io/) plugin.
-  * **[react-browserify-template](https://github.com/petehunt/react-browserify-template)** Quick-start with Browserify.
-
-### Routing
-
-  * **[director](https://github.com/flatiron/director)** (For an example see [TodoMVC](https://github.com/tastejs/todomvc/blob/gh-pages/architecture-examples/react/js/app.jsx#L29)).
-  * **[Backbone](http://backbonejs.org/)** (For an example see [github-issues-viewer](https://github.com/jaredly/github-issues-viewer)).
-  * **[react-router](https://github.com/jaredly/react-router)** (Example coming soon).
-  * **[react-router-component](http://andreypopp.viewdocs.io/react-router-component)**
-
-### Model management
-
-  * **[react.backbone](https://github.com/usepropeller/react.backbone)** Use [Backbone](http://backbonejs.org) models with React.
-  * **[cortex](https://github.com/mquan/cortex/)** A JavaScript library for centrally managing data with React.
-  * **[avers](https://github.com/wereHamster/avers)** A modern client-side model abstraction library.
-
-### Data fetching
-
-  * **[react-async](http://andreypopp.viewdocs.io/react-async)** Adds a `getInitialStateAsync(cb)` method suitable for data fetching on both the client and the server.
-  * **[superagent](http://visionmedia.github.io/superagent/)** A lightweight "isomorphic" library for AJAX requests.
-
-### UI components
-
-  * **[react-bootstrap](https://github.com/stevoland/react-bootstrap)** Bootstrap 3 components built with React.
-  * **[react-topcoat](https://github.com/plaxdan/react-topcoat)** Topcoat components built with React.
-  * **[react-lorem-component](https://github.com/martinandert/react-lorem-component)** Lorem Ipsum placeholder component.
-  * **[wingspan-forms](https://github.com/wingspan/wingspan-forms)** React library for dynamic forms & grids; widgets provided by KendoUI.
-  * **[react-translate-component](https://github.com/martinandert/react-translate-component)** React component for i18n.
+This page has moved to the [GitHub wiki](https://github.com/facebook/react/wiki/Complementary-Tools).

docs/docs/examples.md

@@ -11,7 +11,6 @@ prev: complementary-tools.html
 * **[Instagram.com](http://instagram.com/)** is 100% built on React, both public site and internal tools.
 * **[Facebook.com](http://www.facebook.com/)**'s commenting interface, business management tools, [Lookback video editor](http://facebook.com/lookback/edit), page insights, and most, if not all, new JS development.
 * **[Khan Academy](http://khanacademy.org/)** uses React for most new JS development.
-* **[Shirtstarter](https://www.shirtstarter.com/)** is 100% built on React.
 * **[Sberbank](http://sberbank.ru/moscow/ru/person/)**, Russia's number one bank, is built with React.
 * **[The New York Times's 2014 Red Carpet Project](http://www.nytimes.com/interactive/2014/02/02/fashion/red-carpet-project.html?_r=0)** is built with React.
 

docs/docs/flux-overview.md

@@ -0,0 +1,97 @@
+---
+id: flux-overview
+title: Flux Application Architecture
+layout: docs
+next: flux-todo-list.html
+---
+
+Flux is the application architecture that Facebook uses for building client-side web applications.  It complements React's composable view components by utilizing a unidirectional data flow.  It's more of a pattern rather than a formal framework, and you can start using Flux immediately without a lot of new code.
+
+<figure><iframe width="560" height="315" src="//www.youtube.com/embed/nYkdrAPrdcw?list=PLb0IAmt7-GS188xDYE-u1ShQmFFGbrk0v&start=621" frameborder="0" allowfullscreen></iframe></figure>
+
+Flux applications have three major parts: the dispatcher, the stores, and the views (React components).  These should not be confused with Model-View-Controller.  Controllers do exist in a Flux application, but they are controller-views — views often found at the top of the hierarchy that retrieve data from the stores and pass this data down to their children.  Additionally, actions — dispatcher helper methods — are often used to support a semantic dispatcher API.  It can be useful to think of them as a fourth part of the Flux update cycle.
+
+Flux eschews MVC in favor of a unidirectional data flow. When a user interacts with a React view, the view propagates an action through a central dispatcher, to the various stores that hold the application's data and business logic, which updates all of the views that are affected. This works especially well with React's declarative programming style, which allows the store to send updates without specifying how to transition views between states.
+
+We originally set out to deal correctly with derived data: for example, we wanted to show an unread count for message threads while another view showed a list of threads, with the unread ones highlighted. This was difficult to handle with MVC — marking a single thread as read would update the thread model, and then also need to update the unread count model.  These dependencies and cascading updates often occur in a large MVC application, leading to a tangled weave of data flow and unpredictable results.
+
+Control is inverted with stores: the stores accept updates and reconcile them as appropriate, rather than depending on something external to update its data in a consistent way. Nothing outside the store has any insight into how it manages the data for its domain, helping to keep a clear separation of concerns. This also makes stores more testable than models, especially since stores have no direct setter methods like `setAsRead()`, but instead have only an input point for the payload, which is delivered through the dispatcher and originates with actions.
+
+
+## Structure and Data Flow
+
+Data in a Flux application flows in a single direction, in a cycle:
+
+<pre>
+Views ---> (actions) ----> Dispatcher ---> (registered callback) ---> Stores -------+
+Ʌ                                                                                   |
+|                                                                                   V
++-- (Controller-Views "change" event handlers) ---- (Stores emit "change" events) --+
+</pre>
+
+A unidirectional data flow is central to the Flux pattern, and in fact Flux takes its name from the Latin word for flow. In the above diagram, the dispatcher, stores and views are independent nodes with distinct inputs and outputs. The actions are simply discrete, semantic helper functions that facilitate passing data to the dispatcher. 
+
+All data flows through the dispatcher as a central hub.  Actions most often originate from user interactions with the views, and are nothing more than a call into the dispatcher.  The dispatcher then invokes the callbacks that the stores have registered with it, effectively dispatching the data payload contained in the actions to all stores.  Within their registered callbacks, stores determine which actions they are interested in, and respond accordingly.  The stores then emit a "change" event to alert the controller-views that a change to the data layer has occurred.  Controller-views listen for these events and retrieve data from the stores in an event handler.  The controller-views call their own `render()` method via `setState()` or `forceUpdate()`, updating themselves and all of their children.
+
+This structure allows us to reason easily about our application in a way that is reminiscent of functional reactive programming, or more specifically data-flow programming or flow-based programming, where data flows through the application in a single direction — there are no two-way bindings. Application state is maintained only in the stores, allowing the different parts of the application to remain highly decoupled. Where dependencies do occur between stores, they are kept in a strict hierarchy, with synchronous updates managed by the dispatcher. 
+
+We found that two-way data bindings led to cascading updates, where changing one object led to another object changing, which could also trigger more updates. As applications grew, these cascading updates made it very difficult to predict what would change as the result of one user interaction. When updates can only change data within a single round, the system as a whole becomes more predictable.
+
+Let's look at the various parts of the Flux update cycle up close. A good place to start is the dispatcher. 
+
+
+### A Single Dispatcher 
+
+The dispatcher is the central hub that manages all data flow in a Flux application. It is essentially a registry of callbacks into the stores. Each store registers itself and provides a callback. When the dispatcher responds to an action, all stores in the application are sent the data payload provided by the action via the callbacks in the registry. 
+
+As an application grows, the dispatcher becomes more vital, as it can manage dependencies between stores by invoking the registered callbacks in a specific order.  Stores can declaratively wait for other stores to finish updating, and then update themselves accordingly.
+
+
+### Stores 
+
+Stores contain the application state and logic. Their role is somewhat similar to a model in a traditional MVC, but they manage the state of many objects — they are not instances of one object. Nor are they the same as Backbone's collections. More than simply managing a collection of ORM-style objects, stores manage the application state for a particular __domain__ within the application. 
+
+For example, Facebook's [Lookback Video Editor](https://facebook.com/lookback/edit) utilized a TimeStore that kept track of the playback time position and the playback state. On the other hand, the same application's ImageStore kept track of a collection of images.  The TodoStore in our [TodoMVC example](https://github.com/facebook/react/tree/master/examples/todomvc-flux) is similar in that it manages a collection of to-do items.  A store exhibits characteristics of both a collection of models and a singleton model of a logical domain. 
+
+As mentioned above, a store registers itself with the dispatcher and provides it with a callback. This callback receives the action's data payload as a parameter. The payload contains a type attribute, identifying the action's type. Within the store's registered callback, a switch statement based on the action's type is used to interpret the payload and to provide the proper hooks into the store's internal methods. This allows an action to result in an update to the state of the store, via the dispatcher. After the stores are updated, they broadcast an event declaring that their state has changed, so the views may query the new state and update themselves. 
+
+
+### Views and Controller-Views 
+ 
+React provides the kind of composable views we need for the view layer. Close to the top of the nested view hierarchy, a special kind of view listens for events that are broadcast by the stores that it depends on. One could call this a controller-view, as it provides the glue code to get the data from the stores and to pass this data down the chain of its descendants. We might have one of these controller-views governing any significant section of the page.  
+
+When it receives the event from the store, it first requests the new data it needs via the stores' public getter methods. It then calls its own `setState()` or `forceUpdate()` methods, causing its `render()` method and the `render()` method of all its descendants to run. 
+
+We often pass the entire state of the store down the chain of views in a single object, allowing different descendants to use what they need. In addition to keeping the controller-like behavior at the top of the hierarchy, and thus keeping our descendant views as functionally pure as possible, passing down the entire state of the store in a single object also has the effect of reducing the number of props we need to manage. 
+
+Occasionally we may need to add additional controller-views deeper in the hierarchy to keep components simple.  This might help us to better encapsulate a section of the hierarchy related to a specific  data domain.  Be aware, however, that controller-views deeper in the hierarchy can violate the singular flow of data by introducing a new, potentially conflicting entry point for the data flow.  In making the decision of whether to add a deep controller-view, balance the gain of simpler components against the complexity of multiple data updates flowing into the hierarchy at different points.  These multiple data updates can lead to odd effects, with React's render method getting invoked repeatedly by updates from different controller-views, potentially increasing the difficulty of debugging.
+
+
+### Actions 
+
+The dispatcher exposes a method that allows a view to trigger a dispatch to the stores, and to include a payload of data, or an action. The action construction may be wrapped into a semantic helper method which sends the payload to the dispatcher. For example, we may want to change the text of a to-do item in a to-do list application. We would create an action with a function signature like `updateText(todoId, newText)` in our `TodoActions` module. This method may be invoked from within our views' event handlers, so we can call it in response to a user action. This action method also adds the action type to the payload, so that when the payload is interpreted in the store, it can respond appropriately to a payload with a particular action type. In our example, this type might be named something like `TODO_UPDATE_TEXT`. 
+
+Actions may also come from other places, such as the server. This happens, for example, during data initialization. It may also happen when the server returns an error code or when the server has updates to provide to the application. We'll talk more about server actions in a future article. In this post we're only concerned with the basics of the data flow.
+
+
+### What About that Dispatcher? 
+
+As mentioned earlier, the dispatcher is also able to manage dependencies between stores. This functionality is available through the `waitFor()` method within the Dispatcher class.  We did not need to use this method within the extremely simple [TodoMVC application](https://github.com/facebook/react/tree/master/examples/todomvc-flux), but we have included it [in the example dispatcher](https://github.com/facebook/react/blob/master/examples/todomvc-flux/js/dispatcher/Dispatcher.js#L110) as an example of what a dispatcher should be able to do in a larger, more complex application.
+
+Within the TodoStore's registered callback we could explicitly wait for any dependencies to first update before moving forward: 
+
+```javascript
+case 'TODO_CREATE': 
+  Dispatcher.waitFor([ 
+    PrependedTextStore.dispatcherIndex, 
+    YetAnotherStore.dispatcherIndex 
+  ], function() { 
+    TodoStore.create(PrependedTextStore.getText() + ' ' + action.text); 
+    TodoStore.emit('change'); 
+  }); 
+  break; 
+```
+
+The arguments for `waitFor()` are an array of dispatcher registry indexes, and a final callback to invoke after the callbacks at the given indexes have completed.  Thus the store that is invoking `waitFor()` can depend on the state of another store to inform how it should update its own state.
+
+A problem arises if we create circular dependencies. If Store A waits for Store B, and B waits for A, then we'll have a very bad situation on our hands. We'll need a more robust dispatcher that flags these circular dependencies with console errors, and this is not easily accomplished with promises. Unfortunately, that's a bit beyond the scope of this documentation. In the future we hope to cover how to build a more robust dispatcher and how to initialize, update, and save the state of the application with persistent data, like a web service API.

docs/docs/flux-todo-list.md

@@ -0,0 +1,616 @@
+---
+id: flux-todo-list
+title: Flux TodoMVC Tutorial
+layout: docs
+prev: flux-overview.html
+---
+
+To demonstrate the Flux architecture with some example code, let's take on the classic TodoMVC application. The entire application is available in the React GitHub repo within the [todomvc-flux](https://github.com/facebook/react/tree/master/examples/todomvc-flux) example directory, but let's walk through the development of it a step at a time. 
+
+To begin, we'll need some boilerplate and get up and running with a module system. Node's module system, based on CommonJS, will fit the bill very nicely and we can build off of [react-boilerplate](https://github.com/petehunt/react-boilerplate) to get up and running quickly. Assuming you have npm installed, simply clone the react-boilerplate code from GitHub, and navigate into the resulting directory in Terminal (or whatever CLI application you like). Next run the npm scripts to get up and running: `npm install`, then `npm run build`, and lastly `npm start` to continuously build using Browserify.
+
+The TodoMVC example has all this built into it as well, but if you're starting with react-boilerplate make sure you edit your package.json file to match the file structure and dependencies described in the TodoMVC example's [package.json](https://github.com/facebook/react/tree/master/examples/todomvc-flux/package.json), or else your code won't match up with the explanations below. 
+
+
+Source Code Structure
+--------------------- 
+The resulting index.js file may be used as the entry point into our app, but we'll put most of our code in a 'js' directory. Let's let Browserify do its thing, and now we'll open a new tab in Terminal (or a GUI file browser) to look at the directory. It should look something like this: 
+
+``` 
+myapp 
+  | 
+  + ... 
+  + js
+    |
+    + app.js
+    + bundle.js // generated by Browserify whenever we make changes. 
+  + index.html 
+  + ... 
+``` 
+ 
+Next we'll dive into the js directory, and layout our application's primary directory structure: 
+ 
+``` 
+myapp 
+  | 
+  + ... 
+  + js 
+    | 
+    + actions 
+    + components // all React components, both views and controller-views
+    + constants
+    + dispatcher 
+    + stores 
+    + app.js
+    + bundle.js
+  + index.html
+  + ...
+``` 
+
+Creating a Dispatcher 
+--------------------- 
+
+Now we are ready to create a dispatcher. Here is an naive example of a Dispatcher class, written with JavaScript promises, polyfilled with Jake Archibald's [ES6-Promises](https://github.com/jakearchibald/ES6-Promises) module. 
+
+```javascript 
+var Promise = require('es6-promise').Promise;
+var merge = require('react/lib/merge');
+
+var _callbacks = [];
+var _promises = [];
+
+/**
+ * Add a promise to the queue of callback invocation promises.
+ * @param {function} callback The Store's registered callback.
+ * @param {object} payload The data from the Action.
+ */
+var _addPromise = function(callback, payload) {
+  _promises.push(new Promise(function(resolve, reject) {
+    if (callback(payload)) {
+      resolve(payload);
+    } else {
+      reject(new Error('Dispatcher callback unsuccessful'));
+    }
+  }));
+};
+
+var Dispatcher = function() {};
+Dispatcher.prototype = merge(Dispatcher.prototype, {
+
+  /**
+   * Register a Store's callback so that it may be invoked by an action.
+   * @param {function} callback The callback to be registered.
+   * @return {number} The index of the callback within the _callbacks array.
+   */
+  register: function(callback) {
+    _callbacks.push(callback);
+    return _callbacks.length - 1; // index
+  },
+
+  /**
+   * dispatch
+   * @param  {object} payload The data from the action.
+   */
+  dispatch: function(payload) {
+    // First create array of promises for callbacks to reference.
+    var resolves = [];
+    var rejects = [];
+    _promises = _callbacks.map(function(_, i) {
+      return new Promise(function(resolve, reject) {
+        resolves[i] = resolve;
+        rejects[i] = reject;
+      });
+    });
+    // Dispatch to callbacks and resolve/reject promises.
+    _callbacks.forEach(function(callback, i) {
+      // Callback can return an obj, to resolve, or a promise, to chain.
+      // See waitFor() for why this might be useful.
+      Promise.resolve(callback(payload)).then(function() {
+        resolves[i](payload);
+      }, function() {
+        rejects[i](new Error('Dispatcher callback unsuccessful'));
+      });
+    });
+    _promises = [];
+  }
+}); 
+ 
+module.exports = Dispatcher; 
+``` 
+
+The public API of this basic Dispatcher consists of only two methods: register() and dispatch(). We'll use register() within our stores to register each store's callback. We'll use dispatch() within our actions to trigger the invocation of the callbacks. 
+
+Now we are all set to create a dispatcher that is more specific to our app, which we'll call AppDispatcher. 
+
+```javascript 
+var Dispatcher = require('./Dispatcher');
+
+var merge = require('react/lib/merge');
+
+var AppDispatcher = merge(Dispatcher.prototype, {
+
+  /**
+   * A bridge function between the views and the dispatcher, marking the action
+   * as a view action.  Another variant here could be handleServerAction.
+   * @param  {object} action The data coming from the view.
+   */
+  handleViewAction: function(action) {
+    this.dispatch({
+      source: 'VIEW_ACTION',
+      action: action
+    });
+  }
+
+});
+
+module.exports = AppDispatcher;
+``` 
+
+Now we've created an implementation that is a bit more specific to our needs, with a helper function we can use in the actions coming from our views' event handlers. We might expand on this later to provide a separate helper for server updates, but for now this is all we need. 
+
+
+Creating Stores 
+---------------- 
+
+We can use Node's EventEmitter to get started with a store. We need EventEmitter to broadcast the 'change' event to our controller-views. So let's take a look at what that looks like. I've omitted some of the code for the sake of brevity, but for the full version see [TodoStore.js](https://github.com/Facebook/react/blob/master/examples/todomvc-flux/js/stores/TodoStore.js) in the TodoMVC example code. 
+
+```javascript 
+var AppDispatcher = require('../dispatcher/AppDispatcher'); 
+var EventEmitter = require('events').EventEmitter; 
+var TodoConstants = require('../constants/TodoConstants'); 
+var merge = require('react/lib/merge'); 
+ 
+var CHANGE_EVENT = 'change'; 
+ 
+var _todos = {}; // collection of todo items 
+ 
+/**
+ * Create a TODO item. 
+ * @param {string} text The content of the TODO 
+ */ 
+function create(text) { 
+  // Using the current timestamp in place of a real id. 
+  var id = Date.now(); 
+  _todos[id] = { 
+    id: id, 
+    complete: false, 
+    text: text 
+  }; 
+} 
+ 
+/** 
+ * Delete a TODO item. 
+ * @param {string} id 
+ */ 
+function destroy(id) { 
+  delete _todos[id]; 
+} 
+ 
+var TodoStore = merge(EventEmitter.prototype, { 
+ 
+  /** 
+   * Get the entire collection of TODOs. 
+   * @return {object} 
+   */ 
+  getAll: function() { 
+    return _todos; 
+  }, 
+   
+  emitChange: function() { 
+    this.emit(CHANGE_EVENT); 
+  }, 
+   
+  /** 
+   * @param {function} callback 
+   */ 
+  addChangeListener: function(callback) { 
+    this.on(CHANGE_EVENT, callback); 
+  }, 
+  
+  /** 
+   * @param {function} callback 
+   */ 
+  removeChangeListener: function(callback) { 
+    this.removeListener(CHANGE_EVENT, callback); 
+  } 
+   
+  dispatcherIndex: AppDispatcher.register(function(payload) { 
+    var action = payload.action; 
+    var text; 
+   
+    switch(action.actionType) { 
+      case TodoConstants.TODO_CREATE: 
+        text = action.text.trim(); 
+        if (text !== '') { 
+          create(text); 
+          TodoStore.emitChange(); 
+        } 
+        break; 
+      
+      case TodoConstants.TODO_DESTROY: 
+        destroy(action.id); 
+        TodoStore.emitChange(); 
+        break; 
+      
+      // add more cases for other actionTypes, like TODO_UPDATE, etc. 
+    }
+    
+    return true; // No errors. Needed by promise in Dispatcher. 
+  }) 
+
+}); 
+ 
+module.exports = TodoStore; 
+``` 
+
+There are a few important things to note in the above code. To start, we are maintaining a private data structure called _todos. This object contains all the individual to-do items. Because this variable lives outside the class, but within the closure of the module, it remains private — it cannot be directly changed from the outside. This helps us preserve a distinct input/output interface for the flow of data by making it impossible to update the store without using an action. 
+ 
+Another important part is the registration of the store's callback with the dispatcher. We pass in our payload handling callback to the dispatcher and preserve the index that this store has in the dispatcher's registry. The callback function currently only handles two actionTypes, but later we can add as many as we need. 
+ 
+ 
+Listening to Changes with a Controller-View 
+------------------------------------------- 
+ 
+We need a React component near the top of our component hierarchy to listen for changes in the store. In a larger app, we would have more of these listening components, perhaps one for every section of the page. In Facebook's Ads Creation Tool, we have many of these controller-like views, each governing a specific section of the UI. In the Lookback Video Editor, we only had two: one for the animated preview and one for the image selection interface. Here's one for our TodoMVC example. Again, this is slightly abbreviated, but for the full code you can take a look at the TodoMVC example's [TodoApp.react.js](https://github.com/facebook/react/blob/master/examples/todomvc-flux/js/components/TodoApp.react.js) 
+ 
+```javascript
+/** @jsx React.DOM */ 
+ 
+var Footer = require('./Footer.react'); 
+var Header = require('./Header.react'); 
+var MainSection = require('./MainSection.react'); 
+var React = require('react'); 
+var TodoStore = require('../stores/TodoStore'); 
+ 
+function getTodoState() { 
+  return { 
+    allTodos: TodoStore.getAll() 
+  }; 
+} 
+ 
+var TodoApp = React.createClass({ 
+ 
+  getInitialState: function() { 
+    return getTodoState(); 
+  }, 
+  
+  componentDidMount: function() { 
+    TodoStore.addChangeListener(this._onChange); 
+  }, 
+  
+  componentWillUnmount: function() { 
+    TodoStore.removeChangeListener(this._onChange); 
+  }, 
+ 
+  /**
+   * @return {object}
+   */
+  render: function() {
+  	return (
+      <div>
+        <Header />
+        <MainSection
+          allTodos={this.state.allTodos}
+          areAllComplete={this.state.areAllComplete}
+        />
+        <Footer allTodos={this.state.allTodos} />
+      </div>
+  	);
+  }, 
+ 
+  _onChange: function() { 
+    this.setState(getTodoState()); 
+  } 
+ 
+}); 
+ 
+module.exports = TodoApp; 
+``` 
+
+Now we're in our familiar React territory, utilizing React's lifecycle methods. We set up the initial state of this controller-view in getInitialState(), register an event listener in componentDidMount(), and then clean up after ourselves within componentWillUnmount(). We render a containing div and pass down the collection of states we got from the TodoStore. 
+
+The Header component contains the primary text input for the application, but it does not need to know the state of the store. The MainSection and Footer do need this data, so we pass it down to them. 
+
+More Views 
+---------- 
+At a high level, the React component hierarchy of the app looks like this: 
+
+```javascript
+<TodoApp> 
+  <Header> 
+    <TodoTextInput /> 
+  
+    <MainSection> 
+      <ul> 
+        <TodoItem /> 
+      </ul> 
+    </MainSection> 
+  
+</TodoApp> 
+``` 
+If a TodoItem is in edit mode, it will also render a TodoTextInput as a child. Let's take a look at how some of these components display the data they receive as props, and how they communicate through actions with the dispatcher. 
+The MainSection needs to iterate over the collection of to-do items it received from TodoApp to create the list of TodoItems. In the component's render() method, we can do that iteration like so: 
+
+```javascript
+var allTodos = this.props.allTodos; 
+ 
+for (var key in allTodos) { 
+  todos.push(<TodoItem key={key} todo={allTodos[key]} />); 
+} 
+ 
+return ( 
+  <section id="main"> 
+  <ul id="todo-list">{todos}</ul> 
+); 
+``` 
+Now each TodoItem can display it's own text, and perform actions utilizing it's own ID. Explaining all the different actions that a TodoItem can invoke in the TodoMVC example goes beyond the scope of this article, but let's just take a look at the action that deletes one of the to-do items. Here is an abbreviated version of the TodoItem: 
+
+```javascript
+/** @jsx React.DOM */ 
+ 
+var React = require('react'); 
+var TodoActions = require('../actions/TodoActions'); 
+var TodoTextInput = require('./TodoTextInput.react'); 
+ 
+var TodoItem = React.createClass({ 
+ 
+  propTypes: { 
+    todo: React.PropTypes.object.isRequired 
+  }, 
+ 
+  render: function() { 
+    var todo = this.props.todo; 
+ 
+    return ( 
+      <li 
+        key={todo.id}> 
+        <label> 
+          {todo.text} 
+        </label> 
+        <button className="destroy" onClick={this._onDestroyClick} /> 
+      </li> 
+    ); 
+  }, 
+ 
+  _onDestroyClick: function() { 
+    TodoActions.destroy(this.props.todo.id); 
+  } 
+ 
+}); 
+ 
+module.exports = TodoItem; 
+``` 
+
+With a destroy action available in our library of TodoActions, and a store ready to handle it, connecting the user's interaction with application state changes could not be simpler. We just wrap our onClick handler around the destroy action, provide it with the id, and we're done. Now the user can click the destroy button and kick off the Flux cycle to update the rest of the application. 
+
+Text input, on the other hand, is just a bit more complicated because we need to hang on to the state of the text input within the React component itself. Let's take a look at how TodoTextInput works. 
+
+As you'll see below, with every change to the input, React expects us to update the state of the component. So when we are finally ready to save the text inside the input, we will put the value held in the component's state in the action's payload. This is UI state, rather than application state, and keeping that distinction in mind is a good guide for where state should live. All application state should live in the store, while components occasionally hold on to UI state. Ideally, React components preserve as little state as possible. 
+
+Because TodoTextInput is being used in multiple places within our application, with different behaviors, we'll need to pass the onSave method in as a prop from the component's parent. This allows onSave to invoke different actions depending on where it is used. 
+
+```javascript
+/** @jsx React.DOM */ 
+ 
+var React = require('react'); 
+var ReactPropTypes = React.PropTypes; 
+ 
+var ENTER_KEY_CODE = 13; 
+ 
+var TodoTextInput = React.createClass({ 
+ 
+  propTypes: { 
+    className: ReactPropTypes.string, 
+    id: ReactPropTypes.string, 
+    placeholder: ReactPropTypes.string, 
+    onSave: ReactPropTypes.func.isRequired, 
+    value: ReactPropTypes.string 
+  }, 
+ 
+  getInitialState: function() { 
+    return { 
+      value: this.props.value || '' 
+    }; 
+  },
+ 
+  /** 
+   * @return {object} 
+   */ 
+  render: function() /*object*/ { 
+    return ( 
+      <input 
+        className={this.props.className} 
+        id={this.props.id} 
+        placeholder={this.props.placeholder} 
+        onBlur={this._save} 
+        onChange={this._onChange} 
+        onKeyDown={this._onKeyDown} 
+        value={this.state.value} 
+        autoFocus={true} 
+      /> 
+    ); 
+  }, 
+ 
+  /** 
+   * Invokes the callback passed in as onSave, allowing this component to be 
+   * used in different ways. 
+   */ 
+  _save: function() { 
+    this.props.onSave(this.state.value); 
+    this.setState({ 
+      value: '' 
+    }); 
+  }, 
+ 
+  /** 
+   * @param {object} event 
+   */ 
+  _onChange: function(/*object*/ event) { 
+    this.setState({ 
+      value: event.target.value 
+    }); 
+  }, 
+ 
+  /** 
+   * @param {object} event 
+   */ 
+
+  _onKeyDown: function(event) { 
+    if (event.keyCode === ENTER_KEY_CODE) { 
+      this._save(); 
+    } 
+  } 
+
+}); 
+ 
+module.exports = TodoTextInput; 
+``` 
+
+The Header passes in the onSave method as a prop to allow the TodoTextInput to create new 
+to-do items: 
+
+```javascript
+/** @jsx React.DOM */ 
+ 
+var React = require('react'); 
+var TodoActions = require('../actions/TodoActions'); 
+var TodoTextInput = require('./TodoTextInput.react'); 
+ 
+var Header = React.createClass({ 
+ 
+  /**
+   * @return {object}
+   */
+  render: function() {
+    return (
+      <header id="header">
+        <h1>todos</h1>
+        <TodoTextInput
+          id="new-todo"
+          placeholder="What needs to be done?"
+          onSave={this._onSave}
+        />
+      </header>
+    );
+  }, 
+ 
+  /**
+   * Event handler called within TodoTextInput.
+   * Defining this here allows TodoTextInput to be used in multiple places
+   * in different ways.
+   * @param {string} text
+   */
+  _onSave: function(text) {
+    TodoActions.create(text);
+  } 
+ 
+}); 
+ 
+module.exports = Header; 
+``` 
+
+In a different context, such as in editing mode for an existing to-do item, we might pass an onSave callback that invokes `TodoActions.update(text)` instead. 
+
+
+Creating Semantic Actions 
+------------------------- 
+
+Here is the basic code for the two actions we used above in our views: 
+
+```javascript 
+/** 
+ * TodoActions 
+ */ 
+ 
+var AppDispatcher = require('../dispatcher/AppDispatcher');
+var TodoConstants = require('../constants/TodoConstants');
+
+var TodoActions = {
+
+  /**
+   * @param  {string} text
+   */
+  create: function(text) {
+    AppDispatcher.handleViewAction({
+      actionType: TodoConstants.TODO_CREATE,
+      text: text
+    });
+  }, 
+ 
+  /**
+   * @param  {string} id
+   */
+  destroy: function(id) {
+    AppDispatcher.handleViewAction({
+      actionType: TodoConstants.TODO_DESTROY,
+      id: id
+    });
+  }, 
+ 
+}; 
+ 
+module.exports = TodoActions; 
+``` 
+
+As you can see, we really would not need to have the helpers AppDispatcher.handleViewAction() or TodoActions.create(). We could, in theory, call AppDispatcher.dispatch() directly and provide a payload. But as our application grows, having these helpers keeps the code clean and semantic. It's just a lot cleaner to write TodoActions.destroy(id) instead of writing a whole lot of things that our TodoItem shouldn't have to know about. 
+
+The payload produced by the TodoActions.create() will look like: 
+
+```javascript 
+{ 
+  source: 'VIEW_ACTION', 
+  action: { 
+    type: 'TODO_CREATE', 
+    text: 'Write blog post about Flux' 
+  } 
+} 
+``` 
+
+This payload is provided to the TodoStore through its registered callback. The TodoStore then broadcasts the 'change' event, and the MainSection responds by fetching the new collection of to-do items from the TodoStore and changing its state. This change in state causes the TodoApp component to call its own render() method, and the render() method of all of its descendents. 
+
+Start Me Up 
+-----------
+
+The bootstrap file of our application is app.js. It simply takes the TodoApp component and renders it in the root element of the application. 
+ 
+```javascript
+/** @jsx React.DOM */ 
+ 
+var React = require('react'); 
+ 
+var TodoApp = require('./components/TodoApp.react'); 
+ 
+React.renderComponent( 
+  <TodoApp />, 
+  document.getElementById('todoapp') 
+); 
+``` 
+
+Adding Dependency Management to the Dispatcher 
+----------------------------------------------
+
+As I said previously, our Dispatcher implementation is a bit naive. It's pretty good, but it will not suffice for most applications. We need a way to be able to manage dependencies between Stores. Let's add that functionality with a waitFor() method within the main body of the Dispatcher class. 
+
+We'll need another public method, waitFor(). Note that it returns a Promise that can in turn be returned from the Store callback.
+
+```javascript
+  /**
+   * @param  {array} promisesIndexes
+   * @param  {function} callback
+   */
+  waitFor: function(promiseIndexes, callback) {
+    var selectedPromises = promiseIndexes.map(function(index) {
+      return _promises[index];
+    });
+    return Promise.all(selectedPromises).then(callback);
+  }
+``` 
+
+Now within the TodoStore callback we can explicitly wait for any dependencies to first update before moving forward.  However, if Store A waits for Store B, and B waits for A, then a circular dependency will occur.  A more robust dispatcher is required to flag this scenario with warnings in the console.
+
+The Future of Flux 
+------------------ 
+
+A lot of people ask if Facebook will release Flux as an open source framework. Really, Flux is just an architecture, not a framework.  But perhaps a Flux boilerplate project might make sense, if there is enough interest. Please let us know if you'd like to see us do this.
+
+Thanks for taking the time to read about how we build client-side applications at Facebook. We hope Flux proves as useful to you as it has to us.

docs/docs/getting-started.md

@@ -7,7 +7,7 @@ next: tutorial.html
 
 ## JSFiddle
 
-The easiest way to start hacking on React is using the following JSFiddle Hello Worlds
+The easiest way to start hacking on React is using the following JSFiddle Hello World examples:
 
  * **[React JSFiddle](http://jsfiddle.net/vjeux/kb3gN/)**
  * [React JSFiddle without JSX](http://jsfiddle.net/vjeux/VkebS/)
@@ -48,7 +48,7 @@ The XML syntax inside of JavaScript is called JSX; check out the [JSX syntax](/r
 
 ### Separate File
 
-Your React JSX file can live in a separate file. Create the following `src/helloworld.js`.
+Your React JSX code can live in a separate file. Create the following `src/helloworld.js`.
 
 ```javascript
 /** @jsx React.DOM */
@@ -111,8 +111,8 @@ Update your HTML file as below:
 
 ## Want CommonJS?
 
-If you want to use React within a module system, [fork our repo](http://github.com/facebook/react), `npm install` and run `grunt`. A nice set of CommonJS modules will be generated. Our `jsx` build tool can be integrated into most packaging systems (not just CommonJS) quite easily.
+If you want to use React with [browserify](http://browserify.org/), [webpack](http://webpack.github.io/), or another CommonJS-compatible module system, just use the [`react` npm package](https://www.npmjs.org/package/react). In addition, the `jsx` build tool can be integrated into most packaging systems (not just CommonJS) quite easily.
 
 ## Next Steps
 
-Check out [the tutorial](/react/docs/tutorial.html) and the other examples in the `/examples` directory to learn more. Good luck, and welcome!
+Check out [the tutorial](/react/docs/tutorial.html) and the other examples in the starter kit's `examples` directory to learn more. Good luck, and welcome!

docs/docs/getting-started.zh-CN.md

@@ -0,0 +1,120 @@
+---
+id: getting-started-zh-CN
+title: 入门教程
+layout: docs
+next: tutorial.html
+---
+
+## JSFiddle
+
+开始 Hack React 的最简单的方法是用下面 JSFiddle 的Hello Worlds
+
+ * **[React JSFiddle](http://jsfiddle.net/vjeux/kb3gN/)**
+ * [React JSFiddle without JSX](http://jsfiddle.net/vjeux/VkebS/)
+
+## 入门教程包 (Starter Kit)
+
+开始先下载入门教程包
+
+<div class="buttons-unit downloads">
+  <a href="/react/downloads/react-{{site.react_version}}.zip" class="button">
+    下载入门教程 {{site.react_version}}
+  </a>
+</div>
+
+在入门教程包的根目录，创建一个含有下面代码的 `helloworld.html`
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <script src="build/react.js"></script>
+    <script src="build/JSXTransformer.js"></script>
+  </head>
+  <body>
+    <div id="example"></div>
+    <script type="text/jsx">
+      /** @jsx React.DOM */
+      React.renderComponent(
+        <h1>Hello, world!</h1>,
+        document.getElementById('example')
+      );
+    </script>
+  </body>
+</html>
+```
+
+在 JavaScript 代码里写着 XML 格式的代码称为 JSX；可以去 [JSX 语法](/react/docs/jsx-in-depth.html) 里学习更多 JSX 相关的知识。为了把 JSX 转成标准的 JavaScript，我们用 `<script type="text/jsx">` 标签包裹着含有 JSX 的代码，然后引入 `JSXTransformer.js` 库来实现在浏览器里的代码转换。
+
+### 分离文件
+
+你的 React JSX 代码文件可以写在另外的文件里。新建下面的 `src/helloworld.js`。
+
+```javascript
+/** @jsx React.DOM */
+React.renderComponent(
+  <h1>Hello, world!</h1>,
+  document.getElementById('example')
+);
+```
+
+然后在 `helloworld.html` 引用该文件：
+ 
+```html{10}
+<script type="text/jsx" src="src/helloworld.js"></script>
+```
+
+### 离线转换
+
+先安装命令行工具（依赖 [npm](http://npmjs.org/)）：
+
+```
+npm install -g react-tools
+```
+
+然后把你的 `src/helloworld.js` 文件转成标准的 JavaScript:
+
+```
+jsx --watch src/ build/
+
+```
+
+只要你修改了， `build/helloworld.js` 文件会自动生成。
+
+```javascript{3}
+/** @jsx React.DOM */
+React.renderComponent(
+  React.DOM.h1(null, 'Hello, world!'),
+  document.getElementById('example')
+);
+```
+
+> 注意:
+>
+> 目前注释解析器还是非常严格；为了让它能够找出 `@jsx` 修饰符，有两个限制是必须的。`@jsx` 注释块必须是代码文件第一个注释。注释必须以 `/**` (`/*` 和 `//` 不起作用) 开头。如果解析器找不到 `@jsx` 注释，它就不会转换代码，直接原样输出到文件。
+
+对照下面更新你的 HTML 代码
+
+```html{6,10}
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello React!</title>
+    <script src="build/react.js"></script>
+    <!-- No need for JSXTransformer! -->
+  </head>
+  <body>
+    <div id="example"></div>
+    <script src="build/helloworld.js"></script>
+  </body>
+</html>
+```
+
+## 想用 CommonJS？
+
+如果你想在一个模块系统里使用 React，[fork 我们的代码](http://github.com/facebook/react)， `npm install` 然后运行 `grunt`。一个漂亮的 CommonJS 模块集将会被生成。我们的 `jsx` 转换工具可以很轻松的集成到大部分打包系统里（不仅仅是 CommonJS）。
+
+## 下一步
+
+去看看[入门教程](/react/docs/tutorial.html)，然后学习其他在 `/examples` 目录里的示例代码。祝你好运，欢迎来到 React 的世界。
+

docs/docs/ref-01-top-level-api.md

@@ -11,49 +11,6 @@ next: component-api.html
 `React` is the entry point to the React framework. 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.Children
-
-`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.
-
-#### React.Children.map
-
-```javascript
-object React.Children.map(object children, function fn [, object context])
-```
-
-Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.
-
-#### React.Children.forEach
-
-```javascript
-React.Children.forEach(object children, function fn [, object context])
-```
-
-Like `React.Children.map()` but does not return an object.
-
-#### React.Children.only
-
-```javascript
-object React.Children.only(object children)
-```
-
-Return the only child in `children`. Throws otherwise.
-
-
-### React.DOM
-
-`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
-
-
-### React.initializeTouchEvents
-
-```javascript
-initializeTouchEvents(boolean shouldUseTouch)
-```
-
-Configure React's event system to handle touch events on mobile devices.
-
-
 ### React.createClass
 
 ```javascript
@@ -81,6 +38,12 @@ If the React component was previously rendered into `container`, this will perfo
 
 If the optional callback is provided, it will be executed after the component is rendered or updated.
 
+> Note:
+>
+> `React.renderComponent()` replaces the contents of the container node you
+> pass in. In the future, it may be possible to insert a component to an
+> existing DOM node without overwriting the existing children.
+
 
 ### React.unmountComponentAtNode
 
@@ -90,10 +53,6 @@ boolean unmountComponentAtNode(DOMElement container)
 
 Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.
 
-> Note:
->
-> This method was called `React.unmountAndReleaseReactRootNode` until v0.5. It still works in v0.5 but will be removed in future versions.
-
 
 ### React.renderComponentToString
 
@@ -104,3 +63,68 @@ string renderComponentToString(ReactComponent component)
 Render a component to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes.
 
 If you call `React.renderComponent()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.
+
+
+### React.renderComponentToStaticMarkup
+
+```javascript
+string renderComponentToStaticMarkup(ReactComponent component)
+```
+
+Similar to `renderComponentToString`, except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.
+
+
+### React.DOM
+
+`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
+
+
+### React.PropTypes
+
+`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).
+
+
+### React.initializeTouchEvents
+
+```javascript
+initializeTouchEvents(boolean shouldUseTouch)
+```
+
+Configure React's event system to handle touch events on mobile devices.
+
+
+### React.Children
+
+`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.
+
+#### React.Children.map
+
+```javascript
+object React.Children.map(object children, function fn [, object context])
+```
+
+Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.
+
+#### React.Children.forEach
+
+```javascript
+React.Children.forEach(object children, function fn [, object context])
+```
+
+Like `React.Children.map()` but does not return an object.
+
+#### React.Children.count
+
+```javascript
+number React.Children.count(object children)
+```
+
+Return the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked.
+
+#### React.Children.only
+
+```javascript
+object React.Children.only(object children)
+```
+
+Return the only child in `children`. Throws otherwise.

docs/docs/ref-02-component-api.md

@@ -9,65 +9,7 @@ next: component-specs.html
 
 ## ReactComponent
 
-Component classes created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming these component objects.
-
-
-### getDOMNode
-
-```javascript
-DOMElement getDOMNode()
-```
-
-If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements.
-
-
-### setProps
-
-```javascript
-setProps(object nextProps)
-```
-
-When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render.
-
-> Note:
->
-> This method can only be called on a root-level component. That is, it's only available on the component passed directly to `renderComponent()` 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()`.
-
-
-### replaceProps
-
-```javascript
-replaceProps(object nextProps)
-```
-
-Like `setProps()` but deletes any pre-existing props instead of merging the two objects.
-
-
-### transferPropsTo
-
-```javascript
-ReactComponent transferPropsTo(ReactComponent targetComponent)
-```
-
-Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components:
-
-```javascript
-var Avatar = React.createClass({
-  render: function() {
-    return this.transferPropsTo(
-      <img src={"/avatars/" + this.props.userId + ".png"} userId={null} />
-    );
-  }
-});
-
-// <Avatar userId={17} width={200} height={200} />
-```
-
-Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`.
-
-> Note:
->
-> Use `transferPropsTo` with caution; it encourages tight coupling and makes it easy to accidentally introduce implicit dependencies between components. When in doubt, it's safer to explicitly copy the properties that you need onto the child component.
+Component classes created by `React.createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming these component objects.
 
 
 ### setState
@@ -76,7 +18,7 @@ Properties that are specified directly on the target component instance (such as
 setState(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.  In addition, you can supply an optional callback function that is executed once `setState` is completed.
+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.
 
 > Notes:
 >
@@ -109,6 +51,15 @@ Calling `forceUpdate()` will cause `render()` to be called on the component and
 Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient.
 
 
+### getDOMNode
+
+```javascript
+DOMElement getDOMNode()
+```
+
+If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. When `render` returns `null` or `false`, `this.getDOMNode()` returns `null`.
+
+
 ### isMounted()
 
 ```javascript
@@ -116,3 +67,56 @@ 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()`.
+
+
+### transferPropsTo
+
+```javascript
+ReactComponent transferPropsTo(ReactComponent targetComponent)
+```
+
+Transfer properties from this component to a target component that have not already been set on the target component. After the props are updated, `targetComponent` is returned as a convenience. This function is useful when creating simple HTML-like components:
+
+```javascript
+var Avatar = React.createClass({
+  render: function() {
+    return this.transferPropsTo(
+      <img src={"/avatars/" + this.props.userId + ".png"} userId={null} />
+    );
+  }
+});
+
+// <Avatar userId={17} width={200} height={200} />
+```
+
+Properties that are specified directly on the target component instance (such as `src` and `userId` in the above example) will not be overwritten by `transferPropsTo`.
+
+> Note:
+>
+> Use `transferPropsTo` with caution; it encourages tight coupling and makes it easy to accidentally introduce implicit dependencies between components. When in doubt, it's safer to explicitly copy the properties that you need onto the child component.
+
+
+### setProps
+
+```javascript
+setProps(object nextProps[, function callback])
+```
+
+When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`.
+
+Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed and the component is re-rendered.
+
+> Note:
+>
+> When possible, the declarative approach of calling `React.renderComponent()` 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.renderComponent()` 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()`.
+
+
+### replaceProps
+
+```javascript
+replaceProps(object nextProps[, function callback])
+```
+
+Like `setProps()` but deletes any pre-existing props instead of merging the two objects.

docs/docs/ref-03-component-specs.md

@@ -22,6 +22,8 @@ The `render()` method is required.
 
 When called, it should examine `this.props` and `this.state` and return a single child component. This child component can be either a virtual representation of a native DOM component (such as `<div />` or `React.DOM.div()`) or another composite component that you've defined yourself.
 
+You can also return `null` or `false` to indicate that you don't want anything rendered. Behind the scenes, React renders a `<noscript>` tag to work with our current diffing algorithm. When returning `null` or `false`, `this.getDOMNode()` will return `null`.
+
 The `render()` function should be *pure*, meaning that it does not modify component state, it returns the same result each time it's invoked, and it does not read from or write to the DOM or otherwise interact with the browser (e.g., by using `setTimeout`). If you need to interact with the browser, perform your work in `componentDidMount()` or the other lifecycle methods instead. Keeping `render()` pure makes server rendering more practical and makes components easier to think about.
 
 
@@ -40,9 +42,9 @@ Invoked once before the component is mounted. The return value will be used as t
 object getDefaultProps()
 ```
 
-Invoked once when the component is mounted. Values in the mapping will be set on `this.props` if that prop is not specified by the parent component (i.e. using an `in` check).
+Invoked once and cached when the class is created. Values in the mapping will be set on `this.props` if that prop is not specified by the parent component (i.e. using an `in` check).
 
-This method is invoked before `getInitialState` and therefore cannot rely on `this.state` or use `this.setState`.
+This method is invoked before any instances are created and thus cannot rely on `this.props`. In addition, be aware that any complex objects returned by `getDefaultProps()` will be shared across instances, not copied.
 
 
 ### propTypes
@@ -53,8 +55,6 @@ object propTypes
 
 The `propTypes` object allows you to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).
 
-<!-- TODO: Document propTypes here directly. -->
-
 
 ### mixins
 
@@ -64,8 +64,6 @@ array mixins
 
 The `mixins` array allows you to use mixins to share behavior among multiple components. For more information about mixins, see [Reusable Components](/react/docs/reusable-components.html).
 
-<!-- TODO: Document mixins here directly. -->
-
 
 ### statics
 
@@ -98,7 +96,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#react-composite-components).
 
 
 ## Lifecycle Methods
@@ -112,7 +110,7 @@ Various methods are executed at specific points in a component's lifecycle.
 componentWillMount()
 ```
 
-Invoked once, immediately before the initial rendering occurs. If you call `setState` within this method, `render()` will see the updated state and will be executed only once despite the state change.
+Invoked once, both on the client and server, immediately before the initial rendering occurs. If you call `setState` within this method, `render()` will see the updated state and will be executed only once despite the state change.
 
 
 ### Mounting: componentDidMount
@@ -121,7 +119,7 @@ Invoked once, immediately before the initial rendering occurs. If you call `setS
 componentDidMount()
 ```
 
-Invoked immediately after rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via `this.getDOMNode()`.
+Invoked immediately after rendering occurs, only on the client (not on the server). At this point in the lifecycle, the component has a DOM representation which you can access via `this.getDOMNode()`.
 
 If you want to integrate with other JavaScript frameworks, set timers using `setTimeout` or `setInterval`, or send AJAX requests, perform those operations in this method.
 
@@ -166,7 +164,7 @@ transition to the new props and state will not require a component update.
 
 ```javascript
 shouldComponentUpdate: function(nextProps, nextState) {
-  return !equal(nextProps, this.props) || !equal(nextState, this.state);
+  return nextProps.id !== this.props.id;
 }
 ```
 

docs/docs/ref-04-tags-and-attributes.md

@@ -31,8 +31,8 @@ thead time title tr track u ul var video wbr
 The following SVG elements are supported:
 
 ```
-circle defs g line linearGradient path polygon polyline radialGradient rect
-stop svg text
+circle defs ellipse g line linearGradient mask path pattern polygon polyline
+radialGradient rect stop svg text tspan
 ```
 
 You may also be interested in [react-art](https://github.com/facebook/react-art), a drawing library for React that can render to Canvas, SVG, or VML (for IE8).
@@ -55,23 +55,30 @@ These standard attributes are supported:
 ```
 accept accessKey action allowFullScreen allowTransparency alt async
 autoComplete autoFocus autoPlay cellPadding cellSpacing charSet checked
-className colSpan cols content contentEditable contextMenu controls data
-dateTime defer dir disabled draggable encType form formNoValidate frameBorder
-height hidden href htmlFor httpEquiv icon id label lang list loop max
-maxLength method min multiple name noValidate pattern placeholder poster
-preload radioGroup readOnly rel required role rowSpan rows sandbox scope
-scrollLeft scrollTop seamless selected size span spellCheck src srcDoc step
-style tabIndex target title type value width wmode
+className cols colSpan content contentEditable contextMenu controls coords
+crossOrigin data dateTime defer dir disabled download draggable encType form
+formNoValidate frameBorder height hidden href hrefLang htmlFor httpEquiv icon
+id label lang list loop max maxLength mediaGroup method min multiple muted
+name noValidate pattern placeholder poster preload radioGroup readOnly rel
+required role rows rowSpan sandbox scope scrollLeft scrolling scrollTop
+seamless selected shape size span spellCheck src srcDoc srcSet start step
+style tabIndex target title type useMap value width wmode
 ```
 
-In addition, the non-standard `autoCapitalize` and `autoCorrect` attributes are supported for Mobile Safari, and the `property` attribute is supported for Open Graph `<meta>` tags.
+In addition, the following non-standard attributes are supported:
+
+- `autoCapitalize autoCorrect` for Mobile Safari.
+- `property` for [Open Graph](http://ogp.me/) meta tags.
+- `itemProp itemScope itemType` for [HTML5 microdata](http://schema.org/docs/gs.html).
 
 There is also the React-specific attribute `dangerouslySetInnerHTML` ([more here](/react/docs/special-non-dom-attributes.html)), used for directly inserting HTML strings into a component.
 
 ### SVG Attributes
 
 ```
-cx cy d fill fx fy gradientTransform gradientUnits offset points r rx ry
-spreadMethod stopColor stopOpacity stroke strokeLinecap strokeWidth transform
-version viewBox x1 x2 x y1 y2 y
+cx cy d dx dy fill fillOpacity fontFamily fontSize fx fy gradientTransform
+gradientUnits markerEnd markerMid markerStart offset opacity
+patternContentUnits patternUnits points preserveAspectRatio r rx ry
+spreadMethod stopColor stopOpacity stroke strokeDasharray strokeLinecap
+strokeOpacity strokeWidth textAnchor transform version viewBox x1 x2 x y1 y2 y
 ```

docs/docs/ref-05-events.md

@@ -62,8 +62,9 @@ Properties:
 
 ```javascript
 boolean altKey
-boolean ctrlKey
 Number charCode
+boolean ctrlKey
+function getModifierState(key)
 String key
 Number keyCode
 String locale
@@ -120,6 +121,7 @@ Number buttons
 Number clientX
 Number clientY
 boolean ctrlKey
+function getModifierState(key)
 boolean metaKey
 Number pageX
 Number pageY
@@ -147,6 +149,7 @@ Properties:
 boolean altKey
 DOMTouchList changedTouches
 boolean ctrlKey
+function getModifierState(key)
 boolean metaKey
 boolean shiftKey
 DOMTouchList targetTouches
@@ -181,8 +184,8 @@ onWheel
 Properties:
 
 ```javascript
-Number deltaX
 Number deltaMode
+Number deltaX
 Number deltaY
 Number deltaZ
 ```

docs/docs/ref-08-reconciliation.md

@@ -6,7 +6,7 @@ permalink: reconciliation.html
 prev: special-non-dom-attributes.html
 ---
 
-React key design decision is to make the API seem like it re-renders the whole app on every update. This makes writing applications a lot easier but is also an incredible challenge to make it tractable. This article explains how with powerful heuristics we managed to turn a O(n<sup>3</sup>) problem into a O(n) one.
+React's key design decision is to make the API seem like it re-renders the whole app on every update. This makes writing applications a lot easier but is also an incredible challenge to make it tractable. This article explains how with powerful heuristics we managed to turn a O(n<sup>3</sup>) problem into a O(n) one.
 
 
 ## Motivation
@@ -76,7 +76,7 @@ After the attributes have been updated, we recurse on all the children.
 
 ### Custom Components
 
-We decided that the two custom components are the same. Since components are stateful, we cannot just use the new component and call it a day. React takes all the attributes from the new component and call `component[Will/Did]ReceiveProps()` on the previous one.
+We decided that the two custom components are the same. Since components are stateful, we cannot just use the new component and call it a day. React takes all the attributes from the new component and calls `component[Will/Did]ReceiveProps()` on the previous one.
 
 The previous component is now operational. Its `render()` method is called and the diff algorithm restarts with the new result and the previous result.
 

docs/docs/thinking-in-react.md

@@ -61,7 +61,7 @@ Now that we've identified the components in our mock, let's arrange them into a
 
 ## Step 2: Build a static version in React
 
-<iframe width="100%" height="300" src="http://jsfiddle.net/6wQMG/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="http://jsfiddle.net/n25pd/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
 Now that you have your component hierarchy it's time to start implementing your app. The easiest way is to build a version that takes your data model and renders the UI but has no interactivity. It's easiest to decouple these processes because building a static version requires a lot of typing and no thinking, and adding interactivity requires a lot of thinking and not a lot of typing. We'll see why.
 
@@ -105,7 +105,7 @@ So finally, our state is:
 
 ## Step 4: Identify where your state should live
 
-<iframe width="100%" height="300" src="http://jsfiddle.net/QvHnx/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="http://jsfiddle.net/t53sx/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
 OK, so we've identified what the minimal set of app state is. Next we need to identify which component mutates, or *owns*, this state.
 
@@ -130,7 +130,7 @@ You can start seeing how your application will behave: set `filterText` to `"bal
 
 ## Step 5: Add inverse data flow
 
-<iframe width="100%" height="300" src="http://jsfiddle.net/3Vs3Q/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="http://jsfiddle.net/F8H7p/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
 So far we've built an app that renders correctly as a function of props and state flowing down the hierarchy. Now it's time to support data flowing the other way: the form components deep in the hierarchy need to update the state in `FilterableProductTable`.
 

docs/docs/tutorial.md

@@ -22,7 +22,7 @@ It'll also have a few neat features:
 
 ### Want to skip all this and just see the source?
 
-[It's all on GitHub.](https://github.com/petehunt/react-tutorial)
+[It's all on GitHub.](https://github.com/reactjs/react-tutorial)
 
 ### Getting started
 
@@ -40,9 +40,7 @@ For this tutorial we'll use prebuilt JavaScript files on a CDN. Open up your fav
   <body>
     <div id="content"></div>
     <script type="text/jsx">
-      /**
-       * @jsx React.DOM
-       */
+      /** @jsx React.DOM */
       // The above declaration must remain intact at the top of the script.
       // Your code here
     </script>
@@ -88,18 +86,17 @@ The first thing you'll notice is the XML-ish syntax in your JavaScript. We have
 
 ```javascript
 // tutorial1-raw.js
-var CommentBox = React.createClass({
+var CommentBox = React.createClass({displayName: 'CommentBox',
   render: function() {
     return (
-      React.DOM.div({
-        className: 'commentBox',
-        children: 'Hello, world! I am a CommentBox.'
-      })
+      React.DOM.div({className: "commentBox"},
+        "Hello, world! I am a CommentBox."
+      )
     );
   }
 });
 React.renderComponent(
-  CommentBox({}),
+  CommentBox(null),
   document.getElementById('content')
 );
 ```
@@ -304,12 +301,16 @@ React.renderComponent(
 
 Now that the data is available in the `CommentList`, let's render the comments dynamically:
 
-```javascript{4-6,9}
+```javascript{4-10,13}
 // tutorial10.js
 var CommentList = React.createClass({
   render: function() {
     var commentNodes = this.props.data.map(function (comment) {
-      return <Comment author={comment.author}>{comment.text}</Comment>;
+      return (
+        <Comment author={comment.author}>
+          {comment.text}
+        </Comment>
+      );
     });
     return (
       <div className="commentList">
@@ -385,7 +386,7 @@ var CommentBox = React.createClass({
   getInitialState: function() {
     return {data: []};
   },
-  componentWillMount: function() {
+  componentDidMount: function() {
     $.ajax({
       url: this.props.url,
       dataType: 'json',
@@ -409,9 +410,9 @@ var CommentBox = React.createClass({
 });
 ```
 
-Here, `componentWillMount` is a method called automatically by React before a component is rendered. The key to dynamic updates is the call to `this.setState()`. We replace the old array of comments with the new one from the server and the UI automatically updates itself. Because of this reactivity, it is only a minor change to add live updates. We will use simple polling here but you could easily use WebSockets or other technologies.
+Here, `componentDidMount` is a method called automatically by React when a component is rendered. The key to dynamic updates is the call to `this.setState()`. We replace the old array of comments with the new one from the server and the UI automatically updates itself. Because of this reactivity, it is only a minor change to add live updates. We will use simple polling here but you could easily use WebSockets or other technologies.
 
-```javascript{3,16-17,31}
+```javascript{3,19-20,34}
 // tutorial14.js
 var CommentBox = React.createClass({
   loadCommentsFromServer: function() {
@@ -420,13 +421,16 @@ var CommentBox = React.createClass({
       dataType: 'json',
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
   getInitialState: function() {
     return {data: []};
   },
-  componentWillMount: function() {
+  componentDidMount: function() {
     this.loadCommentsFromServer();
     setInterval(this.loadCommentsFromServer, this.props.pollInterval);
   },
@@ -471,7 +475,7 @@ var CommentForm = React.createClass({
 
 Let's make the form interactive. When the user submits the form, we should clear it, submit a request to the server, and refresh the list of comments. To start, let's listen for the form's submit event and clear it.
 
-```javascript{3-13,16-17,21}
+```javascript{3-13,16-18}
 // tutorial16.js
 var CommentForm = React.createClass({
   handleSubmit: function() {
@@ -489,11 +493,7 @@ var CommentForm = React.createClass({
     return (
       <form className="commentForm" onSubmit={this.handleSubmit}>
         <input type="text" placeholder="Your name" ref="author" />
-        <input
-          type="text"
-          placeholder="Say something..."
-          ref="text"
-        />
+        <input type="text" placeholder="Say something..." ref="text" />
         <input type="submit" value="Post" />
       </form>
     );
@@ -517,7 +517,7 @@ When a user submits a comment, we will need to refresh the list of comments to i
 
 We need to pass data from the child component to its parent. We do this by passing a `callback` in props from parent to child:
 
-```javascript{12-14,28}
+```javascript{15-17,30}
 // tutorial17.js
 var CommentBox = React.createClass({
   loadCommentsFromServer: function() {
@@ -526,6 +526,9 @@ var CommentBox = React.createClass({
       dataType: 'json',
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
@@ -535,7 +538,7 @@ var CommentBox = React.createClass({
   getInitialState: function() {
     return {data: []};
   },
-  componentWillMount: function() {
+  componentDidMount: function() {
     this.loadCommentsFromServer();
     setInterval(this.loadCommentsFromServer, this.props.pollInterval);
   },
@@ -544,9 +547,7 @@ var CommentBox = React.createClass({
       <div className="commentBox">
         <h1>Comments</h1>
         <CommentList data={this.state.data} />
-        <CommentForm
-          onCommentSubmit={this.handleCommentSubmit}
-        />
+        <CommentForm onCommentSubmit={this.handleCommentSubmit} />
       </div>
     );
   }
@@ -570,11 +571,7 @@ var CommentForm = React.createClass({
     return (
       <form className="commentForm" onSubmit={this.handleSubmit}>
         <input type="text" placeholder="Your name" ref="author" />
-        <input
-          type="text"
-          placeholder="Say something..."
-          ref="text"
-        />
+        <input type="text" placeholder="Say something..." ref="text" />
         <input type="submit" value="Post" />
       </form>
     );
@@ -584,7 +581,7 @@ var CommentForm = React.createClass({
 
 Now that the callbacks are in place, all we have to do is submit to the server and refresh the list:
 
-```javascript{13-21}
+```javascript{16-27}
 // tutorial19.js
 var CommentBox = React.createClass({
   loadCommentsFromServer: function() {
@@ -593,6 +590,9 @@ var CommentBox = React.createClass({
       dataType: 'json',
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
@@ -604,13 +604,16 @@ var CommentBox = React.createClass({
       data: comment,
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
   getInitialState: function() {
     return {data: []};
   },
-  componentWillMount: function() {
+  componentDidMount: function() {
     this.loadCommentsFromServer();
     setInterval(this.loadCommentsFromServer, this.props.pollInterval);
   },
@@ -619,9 +622,7 @@ var CommentBox = React.createClass({
       <div className="commentBox">
         <h1>Comments</h1>
         <CommentList data={this.state.data} />
-        <CommentForm
-          onCommentSubmit={this.handleCommentSubmit}
-        />
+        <CommentForm onCommentSubmit={this.handleCommentSubmit} />
       </div>
     );
   }
@@ -632,7 +633,7 @@ var CommentBox = React.createClass({
 
 Our application is now feature complete but it feels slow to have to wait for the request to complete before your comment appears in the list. We can optimistically add this comment to the list to make the app feel faster.
 
-```javascript{13-15}
+```javascript{16-18}
 // tutorial20.js
 var CommentBox = React.createClass({
   loadCommentsFromServer: function() {
@@ -641,6 +642,9 @@ var CommentBox = React.createClass({
       dataType: 'json',
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
@@ -655,13 +659,16 @@ var CommentBox = React.createClass({
       data: comment,
       success: function(data) {
         this.setState({data: data});
+      }.bind(this),
+      error: function(xhr, status, err) {
+        console.error(this.props.url, status, err.toString());
       }.bind(this)
     });
   },
   getInitialState: function() {
     return {data: []};
   },
-  componentWillMount: function() {
+  componentDidMount: function() {
     this.loadCommentsFromServer();
     setInterval(this.loadCommentsFromServer, this.props.pollInterval);
   },
@@ -670,9 +677,7 @@ var CommentBox = React.createClass({
       <div className="commentBox">
         <h1>Comments</h1>
         <CommentList data={this.state.data} />
-        <CommentForm
-          onCommentSubmit={this.handleCommentSubmit}
-        />
+        <CommentForm onCommentSubmit={this.handleCommentSubmit} />
       </div>
     );
   }

docs/docs/videos.md

@@ -13,6 +13,51 @@ next: complementary-tools.html
 
 "At Facebook and Instagram, we’re trying to push the limits of what’s possible on the web with React. My talk will start with a brief introduction to the framework, and then dive into three controversial topics: Throwing out the notion of templates and building views with JavaScript, “re-rendering” your entire application when your data changes, and a lightweight implementation of the DOM and events." -- [Pete Hunt](http://www.petehunt.net/)
 
+
+### Thinking in react - tagtree.tv
+
+A [tagtree.tv](http://tagtree.tv/) video conveying the principles of [Thinking in React](/react/docs/thinking-in-react.html) while building a simple app
+<figure>[![](/react/img/docs/thinking-in-react-tagtree.png)](http://tagtree.tv/thinking-in-react)</figure>
+
+
+### Secrets of the Virtual DOM - MtnWest JS
+
+<iframe width="560" height="315" src="//www.youtube.com/embed/h3KksH8gfcQ" frameborder="0" allowfullscreen></iframe>
+
+"In this talk I’ll be discussing why we built a virtual DOM, how it compares to other systems, and its relevance to the future of browser technologies." -- [Pete Hunt](http://www.petehunt.net/)
+
+### CodeWinds
+
+[Pete Hunt](http://www.petehunt.net/) talked with [Jeff Barczewski](http://jeff.barczewski.com/) about React in CodeWinds Episode 4.
+<figure>[![](/react/img/docs/codewinds-004.png)](http://codewinds.com/4)</figure>
+
+<table width="100%"><tr><td>
+02:08 - What is React and why use it?<br />
+03:08 - The symbiotic relationship of ClojureScript and React<br />
+04:54 - The history of React and why it was created<br />
+09:43 - Updating web page with React without using data binding<br />
+13:11 - Using the virtual DOM to change the browser DOM<br />
+13:57 - Programming with React, render targets HTML, canvas, other<br />
+16:45 - Working with designers. Contrasted with Ember and AngularJS<br />
+21:45 - JSX Compiler bridging HTML and React javascript<br />
+23:50 - Autobuilding JSX and in browser tools for React<br />
+24:50 - Tips and tricks to working with React, getting started<br />
+</td><td>
+27:17 - Rendering HTML on the server with Node.js. Rendering backends<br />
+29:20 - React evolved through survival of the fittest at Facebook<br />
+30:15 - Ideas for having state on server and client, using web sockets.<br />
+32:05 - React-multiuser - distributed shared mutable state using Firebase<br />
+33:03 - Better debugging with React using the state transitions, replaying events<br />
+34:08 - Differences from Web Components<br />
+34:25 - Notable companies using React<br />
+35:16 - Could a React backend plugin be created to target PDF?<br />
+36:30 - Future of React, what's next?<br />
+39:38 - Contributing and getting help<br />
+</td></tr></table>
+
+[Read the episode notes](http://codewinds.com/4)
+
+
 ### JavaScript Jabber
 
 [Pete Hunt](http://www.petehunt.net/) and [Jordan Walke](https://github.com/jordwalke) talked about React in JavaScript Jabber 73.
@@ -57,12 +102,16 @@ By [Steven Luscher](https://github.com/steveluscher)
 
 by [Stoyan Stefanov](http://www.phpied.com/)
 
-### "fun + React + ClojureScript" - Small Talk KyivJS Meetup
+### React, or how to make life simpler - FrontEnd Dev Conf '14
 
-<iframe width="650" height="315" src="//www.youtube.com/embed/R2CGKiNnPFo" frameborder="0" allowfullscreen></iframe>
+<iframe width="560" height="315" src="//www.youtube.com/embed/YJNUK0EA_Jo" frameborder="0" allowfullscreen></iframe>
 
 **In Russian** by [Alexander Solovyov](http://solovyov.net/)
 
 ### "Functional DOM programming" - Meteor DevShop 11
 
 <iframe width="650" height="315" src="//www.youtube.com/embed/qqVbr_LaCIo" frameborder="0" allowfullscreen></iframe>
+
+### "Rethinking Web App Development at Facebook" - Facebook F8 Conference 2014
+
+<iframe width="650" height="315" src="//www.youtube.com/embed/nYkdrAPrdcw" frameborder="0" allowfullscreen></iframe>

docs/downloads.md

@@ -76,6 +76,8 @@ React.renderComponent(...);
 
 If you'd like to use any [add-ons](/react/docs/addons.html), use `var React = require('react/addons');` instead.
 
+**Note:** by default, React will be in development mode. To use React in production mode, set the environment variable `NODE_ENV` to `production`. A minifier that performs dead-code elimination such as [UglifyJS](https://github.com/mishoo/UglifyJS2) is recommended to completely remove the extra code present in development mode.
+
 ## Bower
 
 ```sh

docs/tips/08-controlled-input-null-value.md

@@ -20,5 +20,5 @@ React.renderComponent(<input value="hi" />, mountNode);
 
 setTimeout(function() {
   React.renderComponent(<input value={null} />, mountNode);
-}, 2000);
+}, 1000);
 ```

docs/tips/12-initial-ajax.md

@@ -9,6 +9,8 @@ next: false-in-jsx.html
 
 Fetch data in `componentDidMount`. When the response arrives, store the data in state, triggering a render to update your UI.
 
+When processing the response of an asynchronous request, be sure to check that the component is still mounted before updating its state by using `this.isMounted()`.
+
 This example fetches the desired Github user's latest gist:
 
 ```js
@@ -25,10 +27,12 @@ var UserGist = React.createClass({
   componentDidMount: function() {
     $.get(this.props.source, function(result) {
       var lastGist = result[0];
-      this.setState({
-        username: lastGist.user.login,
-        lastGistUrl: lastGist.html_url
-      });
+      if (this.isMounted()) {
+        this.setState({
+          username: lastGist.owner.login,
+          lastGistUrl: lastGist.html_url
+        });
+      }
     }.bind(this));
   },
 

docs/tips/15-expose-component-functions.md

@@ -4,6 +4,7 @@ title: Expose Component Functions
 layout: tips
 permalink: expose-component-functions.html
 prev: communicate-between-components.html
+next: references-to-components.html
 ---
 
 There's another (uncommon) way of [communicating between components](/react/tips/communicate-between-components.html): simply expose a method on the child component for the parent to call.

docs/tips/16-references-to-components.md

@@ -4,6 +4,7 @@ title: References to Components
 layout: tips
 permalink: references-to-components.html
 prev: expose-component-functions.html
+next: children-undefined.html
 ---
 
 If you're using React components in a larger non-React application or transitioning your code to React, you may need to keep references to components. `React.renderComponent` returns a reference to the mounted component:
@@ -14,12 +15,12 @@ If you're using React components in a larger non-React application or transition
 var myComponent = React.renderComponent(<MyComponent />, myContainer);
 ```
 
-If you pass a variable to 'React.renderComponent`, it's not guaranteed that the component passed in will be the one that's mounted. In cases where you construct a component before mounting it, be sure to reassign your variable:
+Keep in mind, however, that the "constructor" of a component doesn't return a component instance! It's just a **descriptor**: a lightweight representation that tells React what the mounted component should look like.
 
 ```js
 /** @jsx React.DOM */
 
-var myComponent = <MyComponent />;
+var myComponent = <MyComponent />; // This is just a descriptor.
 
 // Some code here...
 
@@ -28,4 +29,4 @@ myComponent = React.renderComponent(myComponent, myContainer);
 
 > Note:
 >
-> This should only ever be used at the top level. Inside components, let your `props` and `state` handle communication with child components, and only reference components via `ref`s.
+> This should only ever be used at the top level. Inside components, let your `props` and `state` handle communication with child components, and only reference components via [refs](http://facebook.github.io/react/docs/more-about-refs.html).

docs/tips/17-children-undefined.md

@@ -0,0 +1,29 @@
+---
+id: children-undefined
+title: this.props.children undefined
+layout: tips
+permalink: children-undefined.html
+prev: references-to-components.html
+---
+
+You can't access the children of your component through `this.props.children`. `this.props.children` designates the children being **passed onto you** by the owner:
+
+```js
+/** @jsx React.DOM */
+
+var App = React.createClass({
+  componentDidMount: function() {
+    // This doesn't refer to the `span`s! It refers to the children between
+    // last line's `<App></App>`, which are undefined.
+    console.log(this.props.children);
+  },
+
+  render: function() {
+    return <div><span/><span/></div>;
+  }
+});
+
+React.renderComponent(<App></App>, mountNode);
+```
+
+To access your own subcomponents (the `span`s), place [refs](http://facebook.github.io/react/docs/more-about-refs.html) on them.

examples/README.md

@@ -0,0 +1,5 @@
+# React Examples
+
+Here are some small React demos. Some use [JSX](http://facebook.github.io/react/docs/jsx-in-depth.html) and some include third-party library integration.
+
+For more fully-featured examples, check out [React TodoMVC](http://todomvc.com/architecture-examples/react/) and [React + Backbone TodoMVC](http://todomvc.com/labs/architecture-examples/react-backbone/).

examples/ballmer-peak/example.js

@@ -18,9 +18,7 @@ var BallmerPeakCalculator = React.createClass({
     this.setState({bac: event.target.value});
   },
   render: function() {
-    var bac;
-    var pct;
-    pct = computeBallmerPeak(this.state.bac);
+    var pct = computeBallmerPeak(this.state.bac);
     if (isNaN(pct)) {
       pct = 'N/A';
     } else {
@@ -34,7 +32,7 @@ var BallmerPeakCalculator = React.createClass({
         <p>
           If your BAC is{' '}
           <input type="text" onChange={this.handleChange} value={this.state.bac} />
-          {', '}then <b>{pct}</b> of your lines of code will have bugs.
+          {', '}then <b>{pct}</b> of your lines of code will be bug free.
         </p>
       </div>
     );

examples/ballmer-peak/index.html

@@ -23,6 +23,9 @@
       Learn more about React at
       <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
     </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script src="../../build/JSXTransformer.js"></script>
     <script type="text/jsx" src="example.js"></script>

examples/basic-commonjs/README.md

@@ -0,0 +1,7 @@
+# Basic example of using React with Browserify
+
+Run `npm install` in the directory to install React from npm. Then run:
+
+    ./node_modules/.bin/browserify --debug --transform reactify ./index.js > ./bundle.js
+
+to produce `bundle.js` with example code and React.

examples/basic-commonjs/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv='Content-type' content='text/html; charset=utf-8'>
+    <title>Basic CommonJS Example with Browserify</title>
+    <link rel="stylesheet" href="../shared/css/base.css" />
+  </head>
+  <body>
+    <h1>Basic CommonJS Example with Browserify</h1>
+    <div id="container">
+      <p>
+        To install React, follow the instructions on
+        <a href="http://www.github.com/facebook/react/">GitHub</a>.
+      </p>
+      <p>
+        If you can see this, React is not working right.
+        If you checked out the source from GitHub make sure to run <code>grunt</code>.
+      </p>
+    </div>
+    <h4>Example Details</h4>
+    <p>This is written with JSX in a CommonJS module and precompiled to vanilla JS by running:</p>
+    <pre>browserify --debug --transform reactify index.js &gt; bundle.js</pre>
+    <p>
+      Learn more about React at
+      <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
+    </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
+    <script src="bundle.js"></script>
+  </body>
+</html>

examples/basic-commonjs/index.js

@@ -0,0 +1,25 @@
+/**
+  * @jsx React.DOM
+  */
+
+var React = require('react');
+
+var ExampleApplication = React.createClass({
+  render: function() {
+    var elapsed = Math.round(this.props.elapsed  / 100);
+    var seconds = elapsed / 10 + (elapsed % 10 ? '' : '.0' );
+    var message =
+      'React has been successfully running for ' + seconds + ' seconds.';
+
+    return <p>{message}</p>;
+  }
+});
+
+var start = new Date().getTime();
+
+setInterval(function() {
+  React.renderComponent(
+    <ExampleApplication elapsed={new Date().getTime() - start} />,
+    document.getElementById('container')
+  );
+}, 50);

examples/basic-commonjs/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "react-basic-commonjs-example",
+  "description": "Basic example of using React with CommonJS",
+  "main": "index.js",
+  "devDependencies": {
+    "envify": "~1.2.1",
+    "react": "~0.10.0",
+    "reactify": "~0.13.1",
+    "browserify": "~3.44.2"
+  },
+  "scripts": {
+    "build": "browserify --debug --transform reactify index.js > bundle.js"
+  }
+}

examples/basic-jsx-external/index.html

@@ -24,6 +24,9 @@
       Learn more about React at
       <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
     </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script src="../../build/JSXTransformer.js"></script>
     <script type="text/jsx" src="example.js"></script>

examples/basic-jsx-harmony/index.html

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv='Content-type' content='text/html; charset=utf-8'>
+    <title>Basic Example with JSX with Harmony</title>
+    <link rel="stylesheet" href="../shared/css/base.css" />
+  </head>
+  <body>
+    <h1>Basic Example with JSX with Harmony</h1>
+    <div id="container">
+      <p>
+        To install React, follow the instructions on
+        <a href="http://www.github.com/facebook/react/">GitHub</a>.
+      </p>
+      <p>
+        If you can see this, React is not working right.
+        If you checked out the source from GitHub make sure to run <code>grunt</code>.
+      </p>
+    </div>
+    <h4>Example Details</h4>
+    <p>This is written with JSX with Harmony (ES6) syntax and transformed in the browser.<p>
+    <p>
+      Learn more about React at
+      <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
+    </p>
+    <script src="../../build/react.js"></script>
+    <script src="../../build/JSXTransformer.js"></script>
+    <script type="text/jsx;harmony=true">
+      /**
+       * @jsx React.DOM
+       */
+      var ExampleApplication = React.createClass({
+        render() {
+          var elapsed = Math.round(this.props.elapsed  / 100);
+          var seconds = elapsed / 10 + (elapsed % 10 ? '' : '.0' );
+          var message =
+            `React has been successfully running for ${seconds} seconds.`;
+
+          return <p>{message}</p>;
+        }
+      });
+      var start = new Date().getTime();
+      setInterval(() => {
+        React.renderComponent(
+          <ExampleApplication elapsed={new Date().getTime() - start} />,
+          document.getElementById('container')
+        );
+      }, 50);
+    </script>
+  </body>
+</html>

examples/basic-jsx-precompile/index.html

@@ -24,6 +24,9 @@ jsx . build/</pre>
       Learn more about React at
       <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
     </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script src="build/example.js"></script>
   </body>

examples/basic-jsx/index.html

@@ -23,6 +23,9 @@
       Learn more about React at
       <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
     </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script src="../../build/JSXTransformer.js"></script>
     <script type="text/jsx">

examples/basic/index.html

@@ -23,6 +23,9 @@
       Learn more about React at
       <a href="http://facebook.github.io/react" target="_blank">facebook.github.io/react</a>.
     </p>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script>
       var ExampleApplication = React.createClass({

examples/jquery-bootstrap/index.html

@@ -9,6 +9,9 @@
 </head>
 <body>
     <div id="jqueryexample"></div>
+    <script src="../shared/thirdparty/es5-shim.min.js"></script>
+    <script src="../shared/thirdparty/es5-sham.min.js"></script>
+    <script src="../shared/thirdparty/console-polyfill.js"></script>
     <script src="../../build/react.js"></script>
     <script src="../../build/JSXTransformer.js"></script>
     <script type="text/javascript" src="../shared/thirdparty/jquery.min.js" charset="utf-8"></script>

examples/jquery-mobile/index.html

@@ -10,6 +10,9 @@
 </head>
 <body class="ui-mobile-viewport ui-overlay-a">
   <div id="content"></div>
+  <script src="../shared/thirdparty/es5-shim.min.js"></script>
+  <script src="../shared/thirdparty/es5-sham.min.js"></script>
+  <script src="../shared/thirdparty/console-polyfill.js"></script>
   <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
   <script src="//code.jquery.com/mobile/1.4.0/jquery.mobile-1.4.0.min.js"></script>
   <script src="../../build/react.js"></script>

examples/server-rendering/README.md

@@ -0,0 +1,44 @@
+# React server rendering example
+
+This example demonstrates how React's server rendering works. Rather than demonstrate a pure-Node solution, this example shows how an app not written in JavaScript (in this case, PHP) can utilize React's server rendering capabilities.
+
+## Overview
+
+You generally start a React app by doing something like this:
+
+```javascript
+React.renderComponent(MyComponent({someData: ...}), document.getElementById('someContainer'));
+```
+
+The problem is that `someContainer` will be an empty HTML element until the JavaScript downloads and executes. This is bad for page load performance (since the user can't see anything until the JS downloads and executes) and is bad for SEO (since the Googlebot can't see any content). React's server rendering solves this problem -- it lets you fill `someContainer` with *static HTML* on the server and "bring it to life" on the client *without* throwing out and re-creating the HTML.
+
+In order to do this, you need to do a few things. You need to be able to run JavaScript on the server, and you need to be able to bundle that JavaScript code and send it down to the browser. This example provides one architecture, but there are many ways to do it.
+
+## Architecture overview
+
+Let's augment an existing PHP app to support server rendering. This architecture runs an Express-based Node web service to run the JavaScript server side. PHP simply uses `file_get_contents()` to send an HTTP request to this service to get the static HTML string.
+
+Browserify is used to run the same code that Node.js is running inside of the browser (aka "isomorphic" JavaScript).
+
+```
++-------------+       +------------------+                                              +----------------------+
+|             |       |                  |  ---- HTTP request (module, props JSON) ---> |                      |
+| The browser | <---> | Existing PHP App |                                              | Node.js react server |
+|             |       |                  |  <--- HTTP response (static HTML string) --- |                      |
++------+------+       +------------------+                                              +----------------------+
+       ^                                                                                            ^
+       |                                                                                            |
+       |              +------------------+                                              +-----------+----------+
+       |              |                  |                                              |                      |
+       +--------------+    Browserify    | <--------------------------------------------+  App code (CommonJS) |
+                      |                  |                                              |                      |
+                      +------------------+                                              +----------------------+
+```
+
+## How to run the demo
+
+  * `npm install` from `jsapp/` and `reactserver/`.
+  * Run `browserify` by doing `npm run build` inside `jsapp/`. This will generate a `webapp/static/bundle.js` file.
+  * Run the node server by doing `npm start` inside `reactserver/`.
+  * Finally, open `index.php` in your browser (on a webserver running PHP, of course). View-source to see the rendered markup.
+  * Kill the `reactserver` and reload `index.php`. You'll notice that the app still works! View-source and you'll see no rendered markup. React is smart enough to recover if server rendering doesn't work.

examples/server-rendering/jsapp/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "example-js-app",
+  "version": "0.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "browserify -t reactify -r react -r ./src/App > ../webapp/static/bundle.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Pete Hunt",
+  "license": "Apache 2",
+  "dependencies": {
+    "envify": "^1.2.1",
+    "react": "^0.10.0",
+    "browserify": "^3.38.0",
+    "reactify": "^0.10.0"
+  }
+}

examples/server-rendering/jsapp/src/App.js

@@ -0,0 +1,10 @@
+/** @jsx React.DOM */
+var React = require('react');
+
+var App = React.createClass({
+  render: function() {
+    return <h1>Hello {this.props.name}!</h1>;
+  }
+});
+
+module.exports = App;

examples/server-rendering/reactserver/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "react-server",
+  "version": "0.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "start": "cd ../jsapp && node ../reactserver/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Pete Hunt",
+  "license": "Apache 2",
+  "dependencies": {
+    "envify": "^1.2.1",
+    "react": "^0.10.0",
+    "express": "^3.5.1",
+    "node-jsx": "^0.10.0"
+  }
+}

examples/server-rendering/reactserver/server.js

@@ -0,0 +1,21 @@
+var React = require('react');
+var express = require('express');
+var path = require('path');
+
+// Transparently support JSX
+require('node-jsx').install();
+
+var app = express();
+
+// All the render server does is take a CommonJS module ID and some JSON props
+// in the querystring and return a static HTML representation of the component.
+// Note that this is a backend service hit by your actual web app. Even so,
+// you would probably put Varnish in front of this in production.
+app.get('/', function(req, res){
+  var component = require(path.resolve(req.query['module']));
+  var props = JSON.parse(req.query['props'] || '{}');
+
+  res.send(React.renderComponentToString(component(props)));
+});
+
+app.listen(3000);

examples/server-rendering/webapp/index.php

@@ -0,0 +1,51 @@
+<?php
+
+// URL to the box running `node server.js`
+define('RENDER_SERVER', 'http://localhost:3000/');
+
+function react_component($module, $props) {
+  $props_json = json_encode($props);
+
+  // Try to server-render the component if the service is available.
+  // If it isn't, no big deal: the client will transparently render
+  // the markup!
+  $server_markup = @file_get_contents(
+    RENDER_SERVER .
+      '?module=' .
+      urlencode($module) .
+      '&props=' .
+      urlencode($props_json)
+  );
+
+  $container_id = uniqid();
+
+  // Generate the code required to run the component on the client.
+  // We assume that the Browserify bundle is loaded in the page already
+  // and that you used -r to get a global require() function that provides
+  // every $module you may request as well as React.
+  // Note that this solution is simple but I don't think it scales to
+  // multiple large pages very well. For that you'd be better off using
+  // webpack.
+  $startup_code =
+    '<script>require(\'react\').renderComponent(require(' . 
+    json_encode($module) .
+    ')(' . $props_json . '), ' . 
+    'document.getElementById(' . json_encode($container_id) . '))' .
+    '</script>';
+
+  $container_markup = '<div id="' . $container_id . '">' . $server_markup . '</div>';
+
+  return $container_markup . $startup_code;
+}
+?>
+
+<html>
+  <head>
+    <title>React server rendering example</title>
+    <script src="static/bundle.js"></script>
+  </head>
+  <body>
+    Welcome to the React server rendering example. Here is a server-rendered React component:
+    <?php echo react_component('./src/App', array('name' => 'Pete')); ?>
+  </body>
+</html>

examples/server-rendering/webapp/static/NOTHING_HERE_YET

@@ -0,0 +1 @@
+Nothing to see here... yet!

examples/shared/thirdparty/console-polyfill.js

@@ -0,0 +1,15 @@
+// Console-polyfill. MIT license.
+// https://github.com/paulmillr/console-polyfill
+// Make it safe to do console.log() always.
+(function(con) {
+  'use strict';
+  var prop, method;
+  var empty = {};
+  var dummy = function() {};
+  var properties = 'memory'.split(',');
+  var methods = ('assert,clear,count,debug,dir,dirxml,error,exception,group,' +
+     'groupCollapsed,groupEnd,info,log,markTimeline,profile,profileEnd,' +
+     'table,time,timeEnd,timeStamp,trace,warn').split(',');
+  while (prop = properties.pop()) con[prop] = con[prop] || empty;
+  while (method = methods.pop()) con[method] = con[method] || dummy;
+})(this.console = this.console || {}); // Using `this` for web workers.