0.5.0 release

Updated README, CHANGELOG, blog post

.gitignore

@@ -5,12 +5,15 @@ node_modules
 static
 .grunt
 _SpecRunner.html
+__benchmarks__
 build/
+.module-cache
 *.gem
 docs/code
 docs/_site
 docs/.sass-cache
 docs/css/react.css
+docs/js/.module-cache
 docs/js/JSXTransformer.js
 docs/js/react.min.js
 docs/js/docs.js

.mailmap

@@ -0,0 +1,21 @@
+Ben Newman <bn@cs.stanford.edu> <benjamn@fb.com>
+Dan Schafer <dschafer@fb.com>
+Harry Hull <harry.hull1@gmail.com>
+Jeff Morrison <jeff@anafx.com> <Jeff@anafx.com>
+Jeff Morrison <jeff@anafx.com> JeffMo <jeffmo@fb.com>
+Jeffrey Lin <lin.jeffrey@gmail.com> <jeffreylin@fb.com>
+Jordan Walke <jordojw@gmail.com>
+Jordan Walke <jordojw@gmail.com> <jordanjcw@fb.com>
+Laurence Rowe <l@lrowe.co.uk> <laurence@lrowe.co.uk>
+Nick Gavalas <njg57@cornell.edu>
+Paul O’Shannessy <paul@oshannessy.com> <poshannessy@fb.com>
+Paul Shen <paul@mnml0.com> <paulshen@fb.com>
+Pete Hunt <floydophone@gmail.com>
+Pete Hunt <floydophone@gmail.com> <pete.hunt@fb.com>
+Pete Hunt <floydophone@gmail.com> <pete@instagram.com>
+Sander Spies <sandermail@gmail.com>
+Sebastian Markbåge <sebastian@calyptus.eu> <sema@fb.com>
+Stoyan Stefanov <ssttoo@ymail.com>
+Timothy Yung <yungsters@gmail.com> <yungsters@fb.com>
+Vjeux <vjeuxx@gmail.com>
+Vjeux <vjeuxx@gmail.com> <vjeux@fb.com>

.travis.yml

@@ -1,3 +1,15 @@
+---
 language: node_js
 node_js:
-  - "0.10"
+- '0.10'
+after_script:
+- curl -F "react=@build/react.js" -F "react.min=@build/react.min.js" -F "transformer=@build/JSXTransformer.js"
+  -F "react-with-addons=@build/react-with-addons.js" -F "react-with-addons.min=@build/react-with-addons.min.js"
+  -F "commit=$TRAVIS_COMMIT" -F "date=`git log --format='%ct' -1`" -F "pull_request=$TRAVIS_PULL_REQUEST"
+  -F "token=$SECRET_TOKEN" -F "branch=$TRAVIS_BRANCH" $SERVER
+env:
+  global:
+  # SERVER
+  - secure: qPvsJ46XzGrdIuPA70b55xQNGF8jcK7N1LN5CCQYYocXLa+fBrl+fTE77QvehOPhqwJXcj6kOxI+sY0KrVwV7gmq2XY2HZGWUSCxTN0SZlNIzqPA80Y7G/yOjA4PUt8LKgP+8tptyhTAY56qf+hgW8BoLiKOdztYF2p+3zXOLuA=
+  # SECRET_TOKEN
+  - secure: dkpPW+VnoqC/okhRdV90m36NcyBFhcwEKL3bNFExAwi0dXnFao8RoFlvnwiPlA23h2faROkMIetXlti6Aju08BgUFV+f9aL6vLyU7gUent4Nd3413zf2fwDtXIWIETg6uLnOpSykGKgCAT/hY3Q2oPLqOoY0OxfgnbqwxkxljrE=

AUTHORS

@@ -0,0 +1,48 @@
+Alexander Solovyov <alexander@solovyov.net>
+Andrew Zich <azich@fb.com>
+Andrey Popp <8mayday@gmail.com>
+Ben Alpert <spicyjalapeno@gmail.com>
+Ben Newman <bn@cs.stanford.edu>
+Brian Rue <brian@rollbar.com>
+Cam Spiers <camspiers@gmail.com>
+Cheng Lou <chenglou92@gmail.com>
+Christian Roman <chroman16@gmail.com>
+Clay Allsopp <clay.allsopp@gmail.com>
+Connor McSheffrey <connor.mcsheffrey@gmail.com>
+Dan Schafer <dschafer@fb.com>
+Daniel Gasienica <dgasienica@zynga.com>
+Daniel Miladinov <dmiladinov@wingspan.com>
+Danny Ben-David <dannybd@fb.com>
+David Hu <davidhu91@gmail.com>
+Eric Clemmons <eric@smarterspam.com>
+Greg Roodt <groodt@gmail.com>
+Harry Hull <harry.hull1@gmail.com>
+Hugo Jobling <me@thisishugo.com>
+Isaac Salier-Hellendag <isaac@fb.com>
+Jakub Malinowski <jakubmal@gmail.com>
+James Ide <ide@fb.com>
+Jamie Wong <jamie.lf.wong@gmail.com>
+Jan Kassens <jkassens@fb.com>
+Jeff Morrison <jeff@anafx.com>
+Jeffrey Lin <lin.jeffrey@gmail.com>
+Jordan Walke <jordojw@gmail.com>
+Josh Duck <josh@fb.com>
+Keito Uchiyama <keito@fb.com>
+Kunal Mehta <k.mehta@berkeley.edu>
+Laurence Rowe <l@lrowe.co.uk>
+Marshall Roch <mroch@fb.com>
+Martin Konicek <mkonicek@fb.com>
+Mathieu M-Gosselin <mathieumg@gmail.com>
+Nick Gavalas <njg57@cornell.edu>
+Owen Coutts <owenc@fb.com>
+Paul O’Shannessy <paul@oshannessy.com>
+Paul Seiffert <paul.seiffert@gmail.com>
+Paul Shen <paul@mnml0.com>
+Pete Hunt <floydophone@gmail.com>
+Peter Cottle <pcottle@fb.com>
+Sander Spies <sandermail@gmail.com>
+Sebastian Markbåge <sebastian@calyptus.eu>
+Stoyan Stefanov <ssttoo@ymail.com>
+Timothy Yung <yungsters@gmail.com>
+Vjeux <vjeuxx@gmail.com>
+Zach Bruggeman <zbruggeman@me.com>

CHANGELOG.md

@@ -0,0 +1,117 @@
+## 0.5.0 (October 16, 2013)
+
+### React
+
+* Memory usage improvements - reduced allocations in core which will help with GC pauses
+* Performance improvements - in addition to speeding things up, we made some tweaks to stay out of slow path code in V8 and Nitro.
+* Standardized prop -> DOM attribute process. This previously resulting in additional type checking and overhead as well as confusing cases for users. Now we will always convert your value to a string before inserting it into the DOM.
+* Support for Selection events.
+* Support for [Composition events](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent).
+* Support for additional DOM properties (`charSet`, `content`, `form`, `httpEquiv`, `rowSpan`, `autoCapitalize`).
+* Support for additional SVG properties (`rx`, `ry`).
+* Support for using `getInitialState` and `getDefaultProps` in mixins.
+* Support mounting into iframes.
+* Bug fixes for controlled form components.
+* Bug fixes for SVG element creation.
+* Added `React.version`.
+* Added `React.isValidClass` - Used to determine if a value is a valid component constructor.
+* Removed `React.autoBind` - This was deprecated in v0.4 and now properly removed.
+* Renamed  `React.unmountAndReleaseReactRootNode` to `React.unmountComponentAtNode`.
+* Began laying down work for refined performance analysis.
+* Better support for server-side rendering - [react-page](https://github.com/facebook/react-page) has helped improve the stability for server-side rendering.
+* Made it possible to use React in environments enforcing a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Security/CSP/Introducing_Content_Security_Policy). This also makes it possible to use React to build Chrome extensions.
+
+### React with Addons (New!)
+
+* Introduced a separate build with several "addons" which we think can help improve the React experience. We plan to deprecate this in the long-term, instead shipping each as standalone pieces. [Read more in the docs](http://facebook.github.io/react/docs/addons.html).
+
+### JSX
+
+* No longer transform `class` to `className` as part of the transform! This is a breaking change - if you were using `class`, you *must* change this to `className` or your components will be visually broken.
+* Added warnings to the in-browser transformer to make it clear it is not intended for production use.
+* Improved compatibility for Windows
+* Improved support for maintaining line numbers when transforming.
+
+
+## 0.4.1 (July 26, 2013)
+
+### React
+
+* `setState` callbacks are now executed in the scope of your component.
+* `click` events now work on Mobile Safari.
+* Prevent a potential error in event handling if `Object.prototype` is extended.
+* Don't set DOM attributes to the string `"undefined"` on update when previously defined.
+* Improved support for `<iframe>` attributes.
+* Added checksums to detect and correct cases where server-side rendering markup mismatches what React expects client-side.
+
+### JSXTransformer
+
+* Improved environment detection so it can be run in a non-browser environment.
+
+
+## 0.4.0 (July 17, 2013)
+
+### React
+
+* Switch from using `id` attribute to `data-reactid` to track DOM nodes. This allows you to integrate with other JS and CSS libraries more easily.
+* Support for more DOM elements and attributes (e.g., `<canvas>`)
+* Improved server-side rendering APIs. `React.renderComponentToString(<component>, callback)` allows you to use React on the server and generate markup which can be sent down to the browser.
+* `prop` improvements: validation and default values. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/11/react-v0-4-prop-validation-and-default-values.html)
+* Support for the `key` prop, which allows for finer control over reconciliation. [Read the docs for details...](http://facebook.github.io/react/docs/multiple-components.html)
+* Removed `React.autoBind`. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/02/react-v0-4-autobind-by-default.html)
+* Improvements to forms. We've written wrappers around `<input>`, `<textarea>`, `<option>`, and `<select>` in order to standardize many inconsistencies in browser implementations. This includes support for `defaultValue`, and improved implementation of the `onChange` event, and circuit completion. [Read the docs for details...](http://facebook.github.io/react/docs/forms.html)
+* We've implemented an improved synthetic event system that conforms to the W3C spec.
+* Updates to your component are batched now, which may result in a significantly faster re-render of components. `this.setState` now takes an optional callback as it's second parameter. If you were using `onClick={this.setState.bind(this, state)}` previously, you'll want to make sure you add a third parameter so that the event is not treated as the callback.
+
+### JSX
+
+* Support for comment nodes `<div>{/* this is a comment and won't be rendered */}</div>`
+* Children are now transformed directly into arguments instead of being wrapped in an array
+  E.g. `<div><Component1/><Component2/></div>` is transformed into `React.DOM.div(null, Component1(null), Component2(null))`.
+  Previously this would be transformed into `React.DOM.div(null, [Component1(null), Component2(null)])`.
+  If you were using React without JSX previously, your code should still work.
+
+### react-tools
+
+* Fixed a number of bugs when transforming directories
+* No longer re-write `require()`s to be relative unless specified
+
+
+## 0.3.3 (June 20, 2013)
+
+### React
+
+* Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(<div/>, domNode); React.renderComponent(<span/>, domNode);` will work now.
+
+### JSX
+
+* Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files.
+
+### react-tools
+
+* Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`.
+* Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache.
+* Freeze our esprima dependency.
+
+
+## 0.3.2 (May 31, 2013)
+
+### JSX
+
+* Improved compatability with other coding styles (specifically, multiple assignments with a single `var`).
+
+### react-tools
+
+* Switch from using the browserified build to shipping individual modules. This allows react-tools to be used with [browserify](https://github.com/substack/node-browserify).
+
+
+## 0.3.1 (May 30, 2013)
+
+### react-tools
+
+* Fix bug in packaging resulting in broken module.
+
+
+## 0.3.0 (May 29, 2013)
+
+* Initial public release

Gruntfile.js

@@ -4,6 +4,7 @@ var exec = require('child_process').exec;
 var jsxTask = require('./grunt/tasks/jsx');
 var browserifyTask = require('./grunt/tasks/browserify');
 var wrapupTask = require('./grunt/tasks/wrapup');
+var populistTask = require('./grunt/tasks/populist');
 var phantomTask = require('./grunt/tasks/phantom');
 var npmTask = require('./grunt/tasks/npm');
 var releaseTasks = require('./grunt/tasks/release');
@@ -16,6 +17,7 @@ module.exports = function(grunt) {
     jsx: require('./grunt/config/jsx/jsx'),
     browserify: require('./grunt/config/browserify'),
     wrapup: require('./grunt/config/wrapup'),
+    populist: require('./grunt/config/populist'),
     phantom: require('./grunt/config/phantom'),
     npm: require('./grunt/config/npm'),
     clean: ['./build', './*.gem', './docs/_site', './examples/shared/*.js'],
@@ -44,32 +46,54 @@ module.exports = function(grunt) {
   // defines global variables instead of using require.
   grunt.registerMultiTask('wrapup', wrapupTask);
 
+  grunt.registerMultiTask('populist', populistTask);
+
   grunt.registerMultiTask('phantom', phantomTask);
 
   grunt.registerMultiTask('npm', npmTask);
 
-  grunt.registerTask('build:basic', ['jsx:debug', 'browserify:basic']);
+  // Check that the version we're exporting is the same one we expect in the
+  // package. This is not an ideal way to do this, but makes sure that we keep
+  // them in sync.
+  var reactVersionExp = /\bReact\.version\s*=\s*['"]([^'"]+)['"];/;
+  grunt.registerTask('version-check', function() {
+    var version = reactVersionExp.exec(
+      grunt.file.read('./build/modules/React.js')
+    )[1];
+    var expectedVersion = grunt.config.data.pkg.version;
+    if (version !== expectedVersion) {
+      grunt.log.error('Versions do not match. Expected %s, saw %s', expectedVersion, version);
+      return false;
+    }
+  });
+
+  grunt.registerTask('build:basic', ['jsx:debug', 'version-check', 'browserify:basic']);
+  grunt.registerTask('build:addons', ['jsx:debug', 'browserify:addons']);
   grunt.registerTask('build:transformer', ['jsx:debug', 'browserify:transformer']);
-  grunt.registerTask('build:min', ['jsx:release', 'browserify:min']);
+  grunt.registerTask('build:min', ['jsx:release', 'version-check', 'browserify:min']);
+  grunt.registerTask('build:addons-min', ['jsx:debug', 'browserify:addonsMin']);
   grunt.registerTask('build:test', [
-    'jsx:debug',
     'jsx:jasmine',
     'jsx:test',
-    'browserify:jasmine',
-    'browserify:test'
+    'version-check',
+    'populist:jasmine',
+    'populist:test'
   ]);
 
-  grunt.registerTask('test', ['build:test', 'phantom:run']);
+  grunt.registerTask('test', ['build:test', 'build:basic', 'phantom:run']);
   grunt.registerTask('npm:test', ['build', 'npm:pack']);
 
   // Optimized build task that does all of our builds. The subtasks will be run
   // in order so we can take advantage of that and only run jsx:debug once.
   grunt.registerTask('build', [
     'jsx:debug',
+    'version-check',
     'browserify:basic',
     'browserify:transformer',
+    'browserify:addons',
     'jsx:release',
     'browserify:min',
+    'browserify:addonsMin',
     'copy:react_docs',
     'compare_size'
   ]);

README.md

@@ -28,20 +28,20 @@ React.renderComponent(
 
 This example will render "Hello John" into a container on the page.
 
-You'll notice that we used an XML-like syntax; [we call it JSX](http://facebook.github.io/react/docs/syntax.html). JSX is not required to use React, but it makes code more readable, and writing it feels like writing HTML. A simple transform is included with React that allows converting JSX into native JavaScript for browsers to digest.
+You'll notice that we used an XML-like syntax; [we call it JSX](http://facebook.github.io/react/docs/jsx-in-depth.html). JSX is not required to use React, but it makes code more readable, and writing it feels like writing HTML. A simple transform is included with React that allows converting JSX into native JavaScript for browsers to digest.
 
 ## Installation
 
-The fastest way to get started is to serve JavaScript from the CDN:
+The fastest way to get started is to serve JavaScript from the CDN (also available on [CDNJS](http://cdnjs.com/#react)):
 
 ```html
 <!-- The core React library -->
-<script src="http://fb.me/react-0.3.2.min.js"></script>
+<script src="http://fb.me/react-0.5.0.js"></script>
 <!-- In-browser JSX transformer, remove when pre-compiling JSX. -->
-<script src="http://fb.me/JSXTransformer-0.3.2.js"></script>
+<script src="http://fb.me/JSXTransformer-0.5.0.js"></script>
 ```
 
-We've also built a [starter kit](http://facebook.github.io/react/downloads/react-0.3.2.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.5.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:
 

bin/jsx

@@ -2,41 +2,11 @@
 "use strict";
 
 var visitors = require('../vendor/fbtransform/visitors').transformVisitors;
-var transform = require('../vendor/fbtransform/lib/transform').transform;
-var debranch = require("../vendor/woodchipper").debranch;
+var transform = require('jstransform').transform;
 
 require("commoner").resolve(function(id) {
-  var context = this;
-
-  // Note that the result of context.getProvidedP() is cached for the
-  // duration of the build, so it is both consistent and cheap to
-  // evaluate multiple times.
-  return context.getProvidedP().then(function(idToPath) {
-    // If a module declares its own identifier using @providesModule
-    // then that identifier will be a key in the idToPath object.
-    if (idToPath.hasOwnProperty(id)) {
-      return context.readFileP(idToPath[id]);
-    }
-
-    // Otherwise assume the identifier maps directly to a path in the
-    // filesystem.
-    return context.readModuleP(id);
-  });
-
+  return this.readModuleP(id);
 }).process(function(id, source) {
-  var context = this;
-
   // This is where JSX, ES6, etc. desugaring happens.
-  source = transform(visitors.react, source).code;
-
-  return context.makePromise(function(callback) {
-    var constants = context.config.constants || {};
-
-    // Debranching means removing any obviously dead code after
-    // replacing constant conditional expressions with literal
-    // (boolean) values.
-    debranch(constants, source, function(source) {
-      callback(null, source);
-    });
-  });
+  return transform(visitors.react, source).code;
 });

bin/jsx-internal

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+"use strict";
+
+var visitors = require('../vendor/fbtransform/visitors').transformVisitors;
+var transform = require('jstransform').transform;
+var propagate = require("../vendor/constants").propagate;
+
+require("commoner").resolve(function(id) {
+  var context = this;
+
+  // Note that the result of context.getProvidedP() is cached for the
+  // duration of the build, so it is both consistent and cheap to
+  // evaluate multiple times.
+  return context.getProvidedP().then(function(idToPath) {
+    // If a module declares its own identifier using @providesModule
+    // then that identifier will be a key in the idToPath object.
+    if (idToPath.hasOwnProperty(id)) {
+      return context.readFileP(idToPath[id]);
+    }
+
+    // Otherwise assume the identifier maps directly to a path in the
+    // filesystem.
+    return context.readModuleP(id);
+  });
+
+}).process(function(id, source) {
+  var context = this;
+  var constants = context.config.constants || {};
+
+  // This is where JSX, ES6, etc. desugaring happens.
+  source = transform(visitors.react, source).code;
+
+  // Constant propagation means removing any obviously dead code after
+  // replacing constant expressions with literal (boolean) values.
+  source = propagate(constants, source);
+
+  if (context.config.mocking) {
+    // Make sure there is exactly one newline at the end of the module.
+    source = source.replace(/\s+$/m, "\n");
+
+    return context.getProvidedP().then(function(idToPath) {
+      if (id !== "mock-modules" &&
+          id !== "mocks" &&
+          id !== "test/all" &&
+          idToPath.hasOwnProperty("mock-modules")) {
+        return source + '\nrequire("mock-modules").register(' +
+          JSON.stringify(id) + ', module);\n';
+      }
+
+      return source;
+    });
+  }
+
+  return source;
+});

docs/Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
+gem 'rake'
+
 # jekyll, which builds it all
 gem 'jekyll', '~>1.0'
 
@@ -14,3 +16,6 @@ gem 'rb-fsevent'
 
 # Redcarpet for Markdown
 gem 'redcarpet'
+
+# For markdown header cleanup
+gem 'sanitize'

docs/Gemfile.lock

@@ -24,13 +24,19 @@ GEM
     liquid (2.5.0)
     maruku (0.6.1)
       syntax (>= 1.0.0)
+    mini_portile (0.5.1)
+    nokogiri (1.6.0)
+      mini_portile (~> 0.5.0)
     posix-spawn (0.3.6)
     pygments.rb (0.5.0)
       posix-spawn (~> 0.3.6)
       yajl-ruby (~> 1.1.0)
+    rake (10.0.4)
     rb-fsevent (0.9.3)
     redcarpet (2.2.2)
     safe_yaml (0.7.1)
+    sanitize (2.0.6)
+      nokogiri (>= 1.4.4)
     sass (3.2.9)
     syntax (1.0.0)
     yajl-ruby (1.1.0)
@@ -41,6 +47,8 @@ PLATFORMS
 DEPENDENCIES
   jekyll (~> 1.0)
   json
+  rake
   rb-fsevent
   redcarpet
+  sanitize
   sass

docs/Rakefile

@@ -13,7 +13,7 @@ task :js do
 end
 
 desc "watch css & js"
-task :watch => [:update_version] do
+task :watch do
   Process.spawn "sass --style=compressed --watch _css/react.scss:css/react.css"
   Process.spawn "../bin/jsx --watch _js js"
   Process.waitall
@@ -30,8 +30,8 @@ task :update_version do
 end
 
 desc "build into ../../react-gh-pages"
-task :release => [:default] do
+task :release => [:update_version, :default] do
   system "jekyll build -d ../../react-gh-pages"
 end
 
-task :default => [:update_version, :css, :js]
+task :default => [:css, :js]

docs/_config.yml

@@ -1,17 +1,71 @@
 ---
-markdown: redcarpet
-name: React
-description: A JavaScript library for building user interfaces
-redcarpet:
-  extensions:
-  - fenced_code_blocks
-react_version: 0.3.2
-pygments: true
+baseurl: /react
+url: http://facebook.github.io
+permalink: /blog/:year/:month/:day/:title.html
 exclude:
 - Gemfile
 - Gemfile.lock
 - README.md
 - Rakefile
-url: http://facebook.github.io
-baseurl: /react
-permalink: /blog/:year/:month/:day/:title.html
+redcarpet:
+  extensions:
+  - fenced_code_blocks
+pygments: true
+name: React
+markdown: redcarpet
+react_version: 0.5.0
+description: A JavaScript library for building user interfaces
+relative_permalinks: true
+paginate: 5
+paginate_path: /blog/page:num
+nav_docs_sections:
+- title: Quick Start
+  items:
+  - id: getting-started
+    title: Getting Started
+  - id: tutorial
+    title: Tutorial
+- title: Guides
+  items:
+  - id: why-react
+    title: Why React?
+  - id: displaying-data
+    title: Displaying Data
+    subitems:
+    - id: jsx-in-depth
+      title: JSX in Depth
+    - id: jsx-gotchas
+      title: JSX Gotchas
+  - id: interactivity-and-dynamic-uis
+    title: Interactivity and Dynamic UIs
+  - id: multiple-components
+    title: Multiple Components
+  - id: reusable-components
+    title: Reusable Components
+  - id: forms
+    title: Forms
+  - id: working-with-the-browser
+    title: Working With the Browser
+    subitems:
+    - id: more-about-refs
+      title: More About Refs
+  - id: tooling-integration
+    title: Tooling Integration
+  - id: addons
+    title: Add-ons
+  - id: examples
+    title: Examples
+- title: Reference
+  items:
+  - id: top-level-api
+    title: Top-Level API
+  - id: component-api
+    title: Component API
+  - id: component-specs
+    title: Component Specs and Lifecycle
+  - id: tags-and-attributes
+    title: Supported Tags and Attributes
+  - id: events
+    title: Event System
+  - id: dom-differences
+    title: DOM Differences

docs/_css/react.scss

@@ -199,13 +199,15 @@ li {
   font-size: 14px;
   // position: fixed;
   float: left;
-  top: 100px;
-  width: 180px;
+  width: 210px;
 
   ul {
     list-style: none;
     margin: 0;
   }
+  ul ul {
+    margin-left: 20px;
+  }
   li {
     margin: 0;
   }
@@ -245,6 +247,12 @@ li {
 
 }
 
+.nav-blog {
+  li {
+    margin-bottom: 5px;
+  }
+}
+
 // Home Page specifics
 
 .home-section {
@@ -282,14 +290,14 @@ li {
   margin-right: 0;
 }
 
-#examples {
-  h3 {
-    color: $darkColor;
-    font-size: 24px;
-    font-weight: normal;
-    margin-bottom: 5px;
-  }
+#examples h3, .home-presentation h3 {
+  color: $darkColor;
+  font-size: 24px;
+  font-weight: normal;
+  margin-bottom: 5px;
+}
 
+#examples {
   p {
     margin: 0 0 25px 0;
     max-width: $twoColumnWidth;
@@ -356,6 +364,22 @@ section.black content {
   padding-bottom: 18px;
 }
 
+/**
+ * Blog
+ */
+
+.blogContent {
+  padding-top: 20px;
+
+  blockquote {
+    padding: 5px 15px;
+    margin: 20px 0;
+    background-color: #f8f5ec;
+    border-left: 5px solid #f7ebc6;
+  }
+
+}
+
 /**
  * Docs
  */
@@ -495,6 +519,10 @@ p {
   margin-bottom: 20px;
 }
 
+figure {
+  text-align: center;
+}
+
 .inner-content {
   float: right;
   width: $skinnyContentWidth;
@@ -658,3 +686,19 @@ p code {
     padding-top: 0;
   }
 }
+
+.post {
+  margin-bottom: 30px;
+}
+
+.pagination {
+  margin-bottom: 30px;
+
+  /* Trick to get the wrapper to expand to fit floating elements */
+  width: 100%;
+  overflow: hidden;
+
+  .next {
+    float: right;
+  }
+}

docs/_includes/nav_blog.html

@@ -1,10 +1,11 @@
-<div class="nav-docs">
+<div class="nav-docs nav-blog">
   <div class="nav-docs-section">
     <h3>Recent posts</h3>
     <ul>
-    {% for post in site.posts %}
-      <li><a href="/react{{ post.url }}"{% if page.title == post.title %} class="active"{% endif %}>{{ post.title }}</a></li>
-    {% endfor %}
+      {% for post in site.posts limit:10 %}
+        <li><a href="/react{{ post.url }}"{% if page.title == post.title %} class="active"{% endif %}>{{ post.title }}</a></li>
+      {% endfor %}
+      <li><a href="/react/blog/all.html">All posts ...</a></li>
     </ul>
   </div>
 </div>

docs/_includes/nav_docs.html

@@ -1,24 +1,27 @@
 <div class="nav-docs">
-  <div class="nav-docs-section">
-    <h3>Getting started</h3>
-    <ul>
-      <li><a href="/react/docs/getting-started.html"{% if page.id == 'docs-getting-started' %} class="active"{% endif %}>Getting Started</a></li>
-      <li><a href="/react/docs/tutorial.html"{% if page.id == 'docs-tutorial' %} class="active"{% endif %}>Tutorial</a></li>
-      <li><a href="/react/docs/common-questions.html"{% if page.id == 'docs-common-questions' %} class="active"{% endif %}>Common Questions</a></li>
-    </ul>
-  </div>
-
-  <div class="nav-docs-section">
-    <h3>Reference</h3>
-    <ul>
-      <li><a href="/react/docs/syntax.html"{% if page.id == 'docs-syntax' %} class="active"{% endif %}>JSX Syntax</a></li>
-      <li><a href="/react/docs/component-basics.html"{% if page.id == 'docs-component-basics' %} class="active"{% endif %}>Component Basics</a></li>
-      <li><a href="/react/docs/component-data.html"{% if page.id == 'docs-component-data' %} class="active"{% endif %}>Component Data</a></li>
-      <li><a href="/react/docs/component-lifecycle.html"{% if page.id == 'docs-component-lifecycle' %} class="active"{% endif %}>Component Lifecycle</a></li>
-      <li><a href="/react/docs/event-handling.html"{% if page.id == 'docs-event-handling' %} class="active"{% endif %}>Event Handling</a></li>
-      <li><a href="/react/docs/advanced-components.html"{% if page.id == 'docs-advanced-components' %} class="active"{% endif %}>Advanced Components</a></li>
-      <li><a href="/react/docs/mixins.html"{% if page.id == 'docs-mixins' %} class="active"{% endif %}>Mixins</a></li>
-      <li><a href="/react/docs/api.html"{% if page.id == 'docs-api' %} class="active"{% endif %}>API</a></li>
-    </ul>
-  </div>
+  {% for section in site.nav_docs_sections %}
+    <div class="nav-docs-section">
+      <h3>{{ section.title }}</h3>
+      <ul>
+        {% for item in section.items %}
+          <li>
+            <a href="/react/docs/{{ item.id }}.html"{% if page.id == item.id %} class="active"{% endif %}>
+              {{ item.title }}
+            </a>
+            {% if item.subitems %}
+              <ul>
+                {% for subitem in item.subitems %}
+                  <li>
+                    <a href="/react/docs/{{ subitem.id }}.html"{% if page.id == subitem.id %} class="active"{% endif %}>
+                      {{ subitem.title }}
+                    </a>
+                  </li>
+                {% endfor %}
+              </ul>
+            {% endif %}
+          </li>
+        {% endfor %}
+      </ul>
+    </div>
+  {% endfor %}
 </div>

docs/_js/examples/markdown.js

@@ -11,16 +11,17 @@ var MarkdownEditor = React.createClass({\n\
   getInitialState: function() {\n\
     return {value: 'Type some *markdown* here!'};\n\
   },\n\
-  handleKeyUp: React.autoBind(function() {\n\
+  handleChange: function() {\n\
     this.setState({value: this.refs.textarea.getDOMNode().value});\n\
-  }),\n\
+  },\n\
   render: function() {\n\
     return (\n\
       <div className=\"MarkdownEditor\">\n\
         <h3>Input</h3>\n\
-        <textarea onKeyUp={this.handleKeyUp} ref=\"textarea\">\n\
-          {this.state.value}\n\
-        </textarea>\n\
+        <textarea\n\
+          onChange={this.handleChange}\n\
+          ref=\"textarea\"\n\
+          defaultValue={this.state.value} />\n\
         <h3>Output</h3>\n\
         <div\n\
           className=\"content\"\n\

docs/_js/examples/timer.js

@@ -7,11 +7,14 @@ var Timer = React.createClass({\n\
   getInitialState: function() {\n\
     return {secondsElapsed: 0};\n\
   },\n\
-  tick: React.autoBind(function() {\n\
+  tick: function() {\n\
     this.setState({secondsElapsed: this.state.secondsElapsed + 1});\n\
-  }),\n\
+  },\n\
   componentDidMount: function() {\n\
-    setInterval(this.tick, 1000);\n\
+    this.interval = setInterval(this.tick, 1000);\n\
+  },\n\
+  componentWillUnmount: function() {\n\
+    clearInterval(this.interval);\n\
   },\n\
   render: function() {\n\
     return React.DOM.div({},\n\

docs/_js/examples/todo.js

@@ -6,48 +6,38 @@ var TODO_COMPONENT = "\
 /** @jsx React.DOM */\n\
 var TodoList = React.createClass({\n\
   render: function() {\n\
-    var items = this.props.items.map(function(item) {\n\
-      return <li>{item}</li>;\n\
-    });\n\
-    return <ul>{items}</ul>;\n\
+    var createItem = function(itemText) {\n\
+      return <li>{itemText}</li>;\n\
+    };\n\
+    return <ul>{this.props.items.map(createItem)}</ul>;\n\
   }\n\
 });\n\
-\n\
-var TodoCreate = React.createClass({\n\
-  handleSubmit: React.autoBind(function() {\n\
-    var textInput = this.refs.textInput.getDOMNode();\n\
-    this.props.onCreate(textInput.value);\n\
-    textInput.value = '';\n\
-    return false;\n\
-  }),\n\
-  render: function() {\n\
-    return (\n\
-      <form onSubmit={this.handleSubmit}>\n\
-        <input type=\"text\" ref=\"textInput\" />\n\
-        <button>Add</button>\n\
-      </form>\n\
-    );\n\
-  }\n\
-});\n\
-\n\
 var TodoApp = React.createClass({\n\
   getInitialState: function() {\n\
-    return {items: []};\n\
+    return {items: [], text: ''};\n\
+  },\n\
+  onChange: function(e) {\n\
+    this.setState({text: e.target.value});\n\
+  },\n\
+  handleSubmit: function(e) {\n\
+    e.preventDefault();\n\
+    var nextItems = this.state.items.concat([this.state.text]);\n\
+    var nextText = '';\n\
+    this.setState({items: nextItems, text: nextText});\n\
   },\n\
-  onItemCreate: React.autoBind(function(value) {\n\
-    this.setState({items: this.state.items.concat([value])});\n\
-  }),\n\
   render: function() {\n\
     return (\n\
       <div>\n\
         <h3>TODO</h3>\n\
         <TodoList items={this.state.items} />\n\
-        <TodoCreate onCreate={this.onItemCreate} />\n\
+        <form onSubmit={this.handleSubmit}>\n\
+          <input onChange={this.onChange} value={this.state.text} />\n\
+          <button>{'Add #' + (this.state.items.length + 1)}</button>\n\
+        </form>\n\
       </div>\n\
     );\n\
   }\n\
 });\n\
-\n\
 React.renderComponent(<TodoApp />, mountNode);\
 ";
 

docs/_js/live_editor.js

@@ -24,7 +24,7 @@ var CodeMirrorEditor = React.createClass({
       matchBrackets: true,
       theme: 'solarized-light'
     });
-    this.editor.on('change', this.onChange.bind(this));
+    this.editor.on('change', this.onChange);
     this.onChange();
   },
   onChange: function() {
@@ -40,7 +40,7 @@ var CodeMirrorEditor = React.createClass({
     if (IS_MOBILE) {
       editor = <pre style={{overflow: 'scroll'}}>{this.props.codeText}</pre>;
     } else {
-      editor = <textarea ref="editor">{this.props.codeText}</textarea>;
+      editor = <textarea ref="editor" defaultValue={this.props.codeText} />;
     }
 
     return (

docs/_layouts/default.html

@@ -10,6 +10,7 @@
   <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">
@@ -35,7 +36,7 @@
     <div class="nav-main">
       <div class="wrap">
         <a class="nav-home" href="/react/index.html">
-          <img class="nav-logo" alt="" src="/react/img/logo_small.png">
+          <img class="nav-logo" alt="" src="/react/img/logo_small.png" width="38" height="38">
           React
         </a>
         <ul class="nav-site">
@@ -72,6 +73,7 @@
       <div class="right">&copy; 2013 Facebook Inc.</div>
     </footer>
   </div>
+  <div id="fb-root"></div>
   <script>
     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
     (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
@@ -79,7 +81,16 @@
     })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
     ga('create', 'UA-41298772-1', 'facebook.github.io');
     ga('send', 'pageview');
+
+    !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
+
+    (function(d, s, id) {
+      var js, fjs = d.getElementsByTagName(s)[0];
+      if (d.getElementById(id)) return;
+      js = d.createElement(s); js.id = id;
+      js.src = "//connect.facebook.net/en_US/all.js#xfbml=1&appId=623268441017527";
+      fjs.parentNode.insertBefore(js, fjs);
+    }(document, 'script', 'facebook-jssdk'));
   </script>
 </body>
 </html>
-

docs/_layouts/docs.html

@@ -19,5 +19,7 @@ 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

@@ -3,7 +3,7 @@ layout: default
 sectionid: blog
 ---
 
-<section class="content wrap documentationContent">
+<section class="content wrap blogContent">
   {% include nav_blog.html %}
   <div class="inner-content">
     <h1>{{ page.title }}</h1>
@@ -14,5 +14,8 @@ sectionid: blog
     <div class="post">
       {{ content }}
     </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/redirect.html

@@ -0,0 +1,6 @@
+<html>
+<head>
+  <meta http-equiv="refresh" content="0; {{ page.destination }}">
+</head>
+<body></body>
+</html>

docs/_plugins/header_links.rb

@@ -0,0 +1,17 @@
+require 'redcarpet'
+require 'sanitize'
+
+# Simple converter that is probably better than RedCarpet's built in TOC id
+# generator (which ends up with things lik id="toc_1"... terrible).
+
+class Redcarpet::Render::HTML
+  def header(title, level)
+    clean_title = Sanitize.clean(title)
+      .downcase
+      .gsub(/\s+/, "-")
+      .gsub(/[^A-Za-z0-9\-_.]/, "")
+
+    return "<h#{level} id=\"#{clean_title}\">#{title}</h#{level}>"
+  end
+end
+

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

@@ -20,8 +20,8 @@ These templates dictate the full set of abstractions that you are allowed to use
 to build your UI.
 
 React approaches building user interfaces differently by breaking them into
-**components**. This means React uses JavaScript to generate markup, which we
-see as an advantage over templates for a few reasons:
+**components**. This means React uses a real, full featured programming language
+to render views, which we see as an advantage over templates for a few reasons:
 
 - **JavaScript is a flexible, powerful programming language** with the ability
   to build abstractions. This is incredibly important in large applications.

docs/_posts/2013-06-12-community-roundup.md

@@ -0,0 +1,48 @@
+---
+title: "Community Round-up #1"
+layout: post
+author: Vjeux
+---
+
+React was open sourced two weeks ago and it's time for a little round-up of what has been going on.
+
+## Khan Academy Question Editor
+
+It looks like [Ben Alpert](http://benalpert.com/) is the first person outside of Facebook and Instagram to push React code to production. We are very grateful for his contributions in form of pull requests, bug reports and presence on IRC ([#reactjs on Freenode](irc://chat.freenode.net/reactjs)). Ben wrote about his experience using React:
+
+> I just rewrote a 2000-line project in React and have now made a handful of pull requests to React. Everything about React I've seen so far seems really well thought-out and I'm proud to be the first non-FB/IG production user of React.
+>
+> The project that I rewrote in React (and am continuing to improve) is the Khan Academy question editor which content creators can use to enter questions and hints that will be presented to students:
+> <figure>[![](/react/img/blog/khan-academy-editor.png)](http://benalpert.com/2013/06/09/using-react-to-speed-up-khan-academy.html)</figure>
+>
+> [Read the full post...](http://benalpert.com/2013/06/09/using-react-to-speed-up-khan-academy.html)
+
+## Pimp my Backbone.View (by replacing it with React)
+
+[Paul Seiffert](https://blog.mayflower.de/) wrote a blog post that explains how to integrate React into Backbone applications.
+
+> React has some interesting concepts for JavaScript view objects that can be used to eliminate this one big problem I have with Backbone.js.
+>
+> As in most MVC implementations (although React is probably just a VC implementation), a view is one portion of the screen that is managed by a controlling object. This object is responsible for deciding when to re-render the view and how to react to user input. With React, these view-controllers objects are called components. A component knows how to render its view and how to handle to the user's interaction with it.
+>
+> The interesting thing is that React is figuring out by itself when to re-render a view and how to do this in the most efficient way.
+>
+> [Read the full post...](https://blog.mayflower.de/3937-Backbone-React.html)
+
+## Using facebook's React with require.js
+
+[Mario Mueller](http://blog.xenji.com/) wrote a menu component in React and was able to easily integrate it with require.js, EventEmitter2 and bower.
+
+> I recently stumbled upon facebook's React library, which is a Javascript library for building reusable frontend components. Even if this lib is only at version 0.3.x it behaves very stable, it is fast and is fun to code. I'm a big fan of require.js, so I tried to use React within the require.js eco system. It was not as hard as expected and here are some examples and some thoughts about it.
+>
+> [Read the full post...](http://blog.xenji.com/2013/06/facebooks-react-require-js.html)
+
+## Origins of React
+
+[Pete Hunt](http://www.petehunt.net/blog/) explained what differentiates React from other JavaScript libraries in [a previous blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html). [Lee Byron](http://leebyron.com/) gives another perspective on Quora:
+
+> React isn't quite like any other popular Javascript libraries, and it solves a very specific problem: complex UI rendering. It's also intended to be used along side many other popular libraries. For example, React works well with Backbone.js, amongst many others.
+>
+> React was born out of frustrations with the common pattern of writing two-way data bindings in complex MVC apps. React is an implementation of one-way data bindings.
+>
+> [Read the full post...](http://www.quora.com/React-JS-Library/How-is-Facebooks-React-JavaScript-library/answer/Lee-Byron?srid=3DcX)

docs/_posts/2013-06-19-community-roundup-2.md

@@ -0,0 +1,71 @@
+---
+title: "Community Round-up #2"
+layout: post
+author: Vjeux
+---
+
+Since the launch we have received a lot of feedback and are actively working on React 0.4. In the meantime, here are the highlights of this week.
+
+## Some quick thoughts on React
+
+[Andrew Greig](http://www.andrewgreig.com/) made a blog post that gives a high level description of what React is.
+
+> I have been using Facebooks recently released Javascript framework called React.js for the last few days and have managed to obtain a rather high level understanding of how it works and formed a good perspective on how it fits in to the entire javascript framework ecosystem.
+>
+> Basically, React is not an MVC framework. It is not a replacement for Backbone or Knockout or Angular, instead it is designed to work with existing frameworks and help extend their functionality.
+>
+> It is designed for building big UIs. The type where you have lots of reusable components that are handling events and presenting and changing some backend data. In a traditional MVC app, React fulfils the role of the View. So you would still need to handle the Model and Controller on your own.
+>
+> I found the best way to utilise React was to pair it with Backbone, with React replacing the Backbone View, or to write your own Model/Data object and have React communicate with that.
+>
+> [Read the full post...](http://www.andrewgreig.com/637/)
+
+## React and Socket.IO Chat Application
+
+[Danial Khosravi](http://danialk.github.io/) made a real-time chat application that interacts with the back-end using Socket.IO.
+
+> A week ago I was playing with AngularJS and [this little chat application](https://github.com/btford/angular-socket-io-im) which uses socket.io and nodejs for realtime communication. Yesterday I saw a post about ReactJS in [EchoJS](http://www.echojs.com/) and started playing with this UI library. After playing a bit with React, I decided to write and chat application using React and I used Bran Ford's Backend for server side of this little app.
+> <figure>[![](/react/img/blog/chatapp.png)](http://danialk.github.io/blog/2013/06/16/reactjs-and-socket-dot-io-chat-application/)</figure>
+>
+> [Read the full post...](http://danialk.github.io/blog/2013/06/16/reactjs-and-socket-dot-io-chat-application/)
+
+## React and Other Frameworks
+
+[Pete Hunt](http://www.petehunt.net/blog/) wrote an answer on Quora comparing React and Angular directives. At the end, he explains how you can make an Angular directive that is in fact being rendered with React.
+
+> To set the record straight: React components are far more powerful than Angular templates; they should be compared with Angular's directives instead. So I took the first Google hit for "AngularJS directive tutorial" (AngularJS Directives Tutorial - Fundoo Solutions), rewrote it in React and compared them. [...]
+>
+> We've designed React from the beginning to work well with other libraries. Angular is no exception. Let's take the original Angular example and use React to implement the fundoo-rating directive.
+>
+> [Read the full post...](http://www.quora.com/Pete-Hunt/Posts/Facebooks-React-vs-AngularJS-A-Closer-Look)
+
+In the same vein, [Markov Twain](https://twitter.com/markov_twain/status/345702941845499906) re-implemented the examples on the front-page [with Ember](http://jsbin.com/azihiw/2/edit) and [Vlad Yazhbin](https://twitter.com/vla) re-implemented the tutorial [with Angular](http://jsfiddle.net/vla/Cdrse/).
+
+## Web Components: React & x-tags
+
+Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.vjeux.com/) wrote a proof of concept that shows how to implement them using React.
+
+> Using [x-tags](http://www.x-tags.org/) from Mozilla, we can write custom tags within the DOM. This is a great opportunity to be able to write reusable components without being tied to a particular library. I wrote [x-react](https://github.com/vjeux/react-xtags/) to have them being rendered in React.
+> <figure>[![](/react/img/blog/xreact.png)](http://blog.vjeux.com/2013/javascript/custom-components-react-x-tags.html)</figure>
+>
+> [Read the full post...](http://blog.vjeux.com/2013/javascript/custom-components-react-x-tags.html)
+
+## React TodoMVC Example
+
+[TodoMVC.com](http://todomvc.com/) is a website that collects various implementations of the same basic Todo app. [Pete Hunt](http://www.petehunt.net/blog/) wrote an idiomatic React version.
+
+> Developers these days are spoiled with choice when it comes to selecting an MV* framework for structuring and organizing their JavaScript web apps.
+>
+> To help solve this problem, we created TodoMVC - a project which offers the same Todo application implemented using MV* concepts in most of the popular JavaScript MV* frameworks of today.
+> <figure>[![](/react/img/blog/todomvc.png)](http://todomvc.com/labs/architecture-examples/react/)</figure>
+>
+> [Read the source code...](https://github.com/tastejs/todomvc/tree/gh-pages/labs/architecture-examples/react)
+
+## JSX is not HTML
+
+Many of you pointed out differences between JSX and HTML. In order to clear up some confusion, we have added some documentation that covers the four main differences:
+
+  - [Whitespace removal](http://facebook.github.io/react/docs/jsx-is-not-html.html)
+  - [HTML Entities](http://facebook.github.io/react/docs/jsx-is-not-html.html)
+  - [Comments](http://facebook.github.io/react/docs/jsx-is-not-html.html)
+  - [Custom HTML Attributes](http://facebook.github.io/react/docs/jsx-is-not-html.html)

docs/_posts/2013-06-21-react-v0-3-3.md

@@ -0,0 +1,24 @@
+---
+title: "React v0.3.3"
+layout: post
+author: Paul O'Shannessy
+---
+
+We have a ton of great stuff coming in v0.4, but in the meantime we're releasing v0.3.3. This release addresses some small issues people were having and simplifies our tools to make them easier to use.
+
+
+## react-tools
+
+* Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`.
+* Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache.
+* Freeze our esprima dependency.
+
+
+## React
+
+* Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(<div/>, domNode); React.renderComponent(<span/>, domNode);` will work now.
+
+
+## JSXTransformer
+
+* Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files.

docs/_posts/2013-06-27-community-roundup-3.md

@@ -0,0 +1,91 @@
+---
+title: "Community Round-up #3"
+layout: post
+author: Vjeux
+---
+
+The highlight of this week is that an interaction-heavy app has been ported to React. React components are solving issues they had with nested views.
+
+## Moving From Backbone To React
+
+[Clay Allsopp](http://twitter.com/clayallsopp) successfully ported [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/), a fairly big, interaction-heavy JavaScript app, to React.
+
+> [<img style="float: right; margin: 0 0 10px 10px;" src="/react/img/blog/propeller-logo.png" />](http://usepropeller.com/blog/posts/from-backbone-to-react/)Subviews involve a lot of easy-to-forget boilerplate that Backbone (by design) doesn't automate. Libraries like Backbone.Marionette offer more abstractions to make view nesting easier, but they're all limited by the fact that Backbone delegates how and went view-document attachment occurs to the application code.
+>
+> React, on the other hand, manages the DOM and only exposes real nodes at select points in its API. The "elements" you code in React are actually objects which wrap DOM nodes, not the actual objects which get inserted into the DOM. Internally, React converts those abstractions into actual DOMElements and fills out the document accordingly. [...]
+>
+> We moved about 20 different Backbone view classes to React over the past few weeks, including the live-preview pane that you see in our little iOS demo. Most importantly, it's allowed us to put energy into making each component work great on its own, instead of spending extra cycles to ensure they function in unison. For that reason, we think React is a more scalable way to build view-intensive apps than Backbone alone, and it doesn't require you to drop-everything-and-refactor like a move to Ember or Angular would demand.
+>
+> [Read the full post...](http://usepropeller.com/blog/posts/from-backbone-to-react/)
+
+## Grunt Task for JSX
+
+[Eric Clemmons](http://ericclemmons.github.io/) wrote a task for [Grunt](http://gruntjs.com/) that applies the JSX transformation to your Javascript files. It also works with [Browserify](http://browserify.org/) if you want all your files to be concatenated and minified together.
+
+> Grunt task for compiling Facebook React's .jsx templates into .js
+>
+> ```javascript
+grunt.initConfig({
+  react: {
+    app: {
+      options: { extension: 'js' },
+      files: { 'path/to/output/dir': 'path/to/jsx/templates/dir' }
+```
+>
+> It also works great with `grunt-browserify`!
+>
+> ```javascript
+browserify: {
+  options: {
+    transform: [ require('grunt-react').browserify ]
+  },
+  app: {
+    src: 'path/to/source/main.js',
+    dest: 'path/to/target/output.js'
+```
+>
+> [Check out the project ...](https://github.com/ericclemmons/grunt-react)
+
+## Backbone/Handlebars Nested Views
+
+[Joel Burget](http://joelburget.com/) wrote a blog post talking about the way we would write React-like components in Backbone and Handlebars.
+
+> The problem here is that we're trying to maniplate a tree, but there's a textual layer we have to go through. Our views are represented as a tree - the subviews are children of CommentCollectionView - and they end up as part of a tree in the DOM. But there's a Handlebars layer in the middle (which deals in flat strings), so the hierarchy must be destructed and rebuilt when we render.
+>
+> What does it take to render a collection view? In the Backbone/Handlebars view of the world you have to render the template (with stubs), render each subview which replaces a stub, and keep a reference to each subview (or anything within the view that could change in the future).
+>
+> So while our view is conceptually hierarchical, due to the fact that it has to go through a flat textual representation, we need to do a lot of extra work to reassemble that structure after rendering.
+>
+> [Read the full post...](http://joelburget.com/react/)
+
+## JSRomandie Meetup
+
+[Renault John Lecoultre](https://twitter.com/renajohn/) from [BugBuster](http://www.bugbuster.com) did a React introduction talk at a JS meetup called [JS Romandie](https://twitter.com/jsromandie) last week.
+
+<script async class="speakerdeck-embed" data-id="888a9d50c01b01300df36658d0894ac1" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
+
+## CoffeeScript integration
+
+[Vjeux](http://blog.vjeux.com/) used the fact that JSX is just a syntactic sugar on-top of regular JS to rewrite the React front-page examples in CoffeeScript.
+
+> Multiple people asked what's the story about JSX and CoffeeScript. There is no JSX pre-processor for CoffeeScript and I'm not aware of anyone working on it. Fortunately, CoffeeScript is pretty expressive and we can play around the syntax to come up with something that is usable.
+>
+> ```javascript
+{div, h3, textarea} = React.DOM
+(div {className: 'MarkdownEditor'}, [
+  (h3 {}, 'Input'),
+  (textarea {onKeyUp: @handleKeyUp, ref: 'textarea'},
+    @state.value
+  )
+])
+```
+>
+> [Read the full post...](http://blog.vjeux.com/2013/javascript/react-coffeescript.html)
+
+## Tutorial in Plain Javascript
+
+We've seen a lot of people comparing React with various frameworks. [Ricardo Tomasi](http://ricardo.cc/) decided to re-implement the tutorial without any framework, just plain Javascript.
+
+> Facebook & Instagram launched the React framework and an accompanying tutorial. Developer Vlad Yazhbin decided to rewrite that using AngularJS. The end result is pretty neat, but if you're like me you will not actually appreciate the HTML speaking for itself and doing all the hard work. So let's see what that looks like in plain javascript.
+>
+> [Read the full post...](http://ricardo.cc/2013/06/07/react-tutorial-rewritten-in-plain-javascript.html)

docs/_posts/2013-07-02-react-v0-4-autobind-by-default.md

@@ -0,0 +1,52 @@
+---
+title: "New in React v0.4: Autobind by Default"
+layout: post
+author: Paul O'Shannessy
+---
+
+React v0.4 is very close to completion. As we finish it off, we'd like to share with you some of the major changes we've made since v0.3. This is the first of several posts we'll be making over the next week.
+
+
+## What is React.autoBind?
+
+If you take a look at most of our current examples, you'll see us using `React.autoBind` for event handlers. This is used in place of `Function.prototype.bind`. Remember that in JS, [function calls are late-bound](http://bonsaiden.github.io/JavaScript-Garden/#function.this). That means that if you simply pass a function around, the `this` used inside won't necessarily be the `this` you expect. `Function.prototype.bind` creates a new, properly bound, function so that when called, `this` is exactly what you expect it to be.
+
+Before we launched React, we would write this:
+
+```js{4}
+React.createClass({
+  onClick: function(event) {/* do something with this */},
+  render: function() {
+    return <button onClick={this.onClick.bind(this)} />;
+  }
+});
+```
+
+We wrote `React.autoBind` as a way to cache the function creation and save on memory usage. Since `render` can get called multiple times, if you used `this.onClick.bind(this)` you would actually create a new function on each pass. With React v0.3 you were able to write this instead:
+
+```js{2,4}
+React.createClass({
+  onClick: React.autoBind(function(event) {/* do something with this */}),
+  render: function() {
+    return <button onClick={this.onClick} />;
+  }
+});
+```
+
+
+## What's Changing in v0.4?
+
+After using `React.autoBind` for a few weeks, we realized that there were very few times that we didn't want that behavior. So we made it the default! Now all methods defined within `React.createClass` will already be bound to the correct instance.
+
+Starting with v0.4 you can just write this:
+
+```js{2,4}
+React.createClass({
+  onClick: function(event) {/* do something with this */},
+  render: function() {
+    return <button onClick={this.onClick} />;
+  }
+});
+```
+
+For v0.4 we will simply be making `React.autoBind` a no-op — it will just return the function you pass to it. Most likely you won't have to change your code to account for this change, though we encourage you to update. We'll publish a migration guide documenting this and other changes that come along with React v0.4.

docs/_posts/2013-07-03-community-roundup-4.md

@@ -0,0 +1,58 @@
+---
+title: "Community Round-up #4"
+layout: post
+author: Vjeux
+---
+
+React reconciliation process appears to be very well suited to implement a text editor with a live preview as people at Khan Academy show us.
+
+## Khan Academy
+
+[Ben Kamens](http://bjk5.com/) explains how [Ben Alpert](http://benalpert.com/) and [Joel Burget](http://joelburget.com/) are promoting React inside of [Khan Academy](https://www.khanacademy.org/). They now have three projects in the works using React.
+
+> Recently two Khan Academy devs dropped into our team chat and said they were gonna use React to write a new feature. They even hinted that we may want to adopt it product-wide.
+>
+> "The library is only a week old. It's a brand new way of thinking about things. We're the first to use it outside of Facebook. Heck, even the React devs were surprised to hear we're using this in production!!!"
+>
+> [Read the full post...](http://bjk5.com/post/53742233351/getting-your-team-to-adopt-new-technology)
+
+The best part is the demo of how React reconciliation process makes live editing more user-friendly.
+
+> Our renderer, post-React, is on the left. A typical math editor's preview is on the right.
+> <figure>[<img src="/react/img/blog/monkeys.gif" width="70%" />](http://bjk5.com/post/53742233351/getting-your-team-to-adopt-new-technology)</figure>
+
+## React Snippets
+
+Over the past several weeks, members of our team, [Pete Hunt](http://www.petehunt.net/) and [Paul O'Shannessy](http://zpao.com/), answered many questions that were asked in the [React group](https://groups.google.com/forum/#!forum/reactjs). They give a good overview of how to integrate React with other libraries and APIs through the use of [Mixins](/react/docs/reusable-components.html) and [Lifecycle Methods](/react/docs/working-with-the-browser.html).
+
+> [Listening Scroll Event](https://groups.google.com/forum/#!topic/reactjs/l6PnP8qbofk)
+>
+>  * [JSFiddle](http://jsfiddle.net/aabeL/1/): Basically I've given you two mixins. The first lets you react to global scroll events. The second is, IMO, much more useful: it gives you scroll start and scroll end events, which you can use with setState() to create components that react based on whether the user is scrolling or not.
+>
+> [Fade-in Transition](https://groups.google.com/forum/#!topic/reactjs/RVAY_eQmdpo)
+>
+>  * [JSFiddle](http://jsfiddle.net/ufe8k/1/): Creating a new `<FadeInWhenAdded>` component and using jQuery `.fadeIn()` function on the DOM node.
+>  * [JSFiddle](http://jsfiddle.net/R8f5L/5/): Using CSS transition instead.
+>
+> [Socket.IO Integration](https://groups.google.com/forum/#!topic/reactjs/pyUZBRWcHB4)
+>
+> * [Gist](https://gist.github.com/zpao/5686416): The big thing to notice is that my component is pretty dumb (it doesn't have to be but that's how I chose to model it). All it does is render itself based on the props that are passed in. renderOrUpdate is where the "magic" happens.
+> * [Gist](https://gist.github.com/petehunt/5687230): This example is doing everything -- including the IO -- inside of a single React component.
+> * [Gist](https://gist.github.com/petehunt/5687276): One pattern that we use at Instagram a lot is to employ separation of concerns and consolidate I/O and state into components higher in the hierarchy to keep the rest of the components mostly stateless and purely display.
+>
+> [Sortable jQuery Plugin Integration](https://groups.google.com/forum/#!topic/reactjs/mHfBGI3Qwz4)
+>
+> * [JSFiddle](http://jsfiddle.net/LQxy7/): Your React component simply render empty divs, and then in componentDidMount() you call React.renderComponent() on each of those divs to set up a new root React tree. Be sure to explicitly unmountAndReleaseReactRootNode() for each component in componentWillUnmount().
+
+## Introduction to React Screencast
+
+[Pete Hunt](http://www.petehunt.net/) recorded himself implementing a simple `<Blink>` tag in React.
+
+<figure><iframe src="http://player.vimeo.com/video/67248575" width="500" height="340" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe></figure>
+
+## Snake in React
+
+[Tom Occhino](http://tomocchino.com/) implemented Snake in 150 lines with React.
+
+> [Check the source on Github](https://github.com/tomocchino/react-snake/blob/master/src/snake.js)
+> <figure>[![](/react/img/blog/snake.png)](http://tomocchino.github.io/react-snake/)</figure>

docs/_posts/2013-07-11-react-v0-4-prop-validation-and-default-values.md

@@ -0,0 +1,63 @@
+---
+title: "New in React v0.4: Prop Validation and Default Values"
+layout: post
+author: Paul O'Shannessy
+---
+
+Many of the questions we got following the public launch of React revolved around `props`, specifically that people wanted to do validation and to make sure their components had sensible defaults.
+
+
+## Validation
+
+Oftentimes you want to validate your `props` before you use them. Perhaps you want to ensure they are a specific type. Or maybe you want to restrict your prop to specific values. Or maybe you want to make a specific prop required. This was always possible — you could have written validations in your `render` or `componentWillReceiveProps` functions, but that gets clunky fast.
+
+React v0.4 will provide a nice easy way for you to use built-in validators, or to even write your own.
+
+```js
+React.createClass({
+  propTypes: {
+    // An optional string prop named "description".
+    description: React.PropTypes.string,
+
+    // A required enum prop named "category".
+    category: React.PropTypes.oneOf(['News','Photos']).isRequired,
+
+    // A prop named "dialog" that requires an instance of Dialog.
+    dialog: React.PropTypes.instanceOf(Dialog).isRequired
+  },
+  ...
+});
+```
+
+
+## Default Values
+
+One common pattern we've seen with our React code is to do something like this:
+
+```js
+React.createClass({
+  render: function() {
+    var value = this.props.value || 'default value';
+    return <div>{value}</div>;
+  }
+});
+```
+
+Do this for a few `props` across a few components and now you have a lot of redundant code. Starting with React v0.4, you can provide default values in a declarative way:
+
+```js
+React.createClass({
+  getDefaultProps: function() {
+    return {
+      value: 'default value'
+    };
+  }
+  ...
+});
+```
+
+We will use the cached result of this function before each `render`. We also perform all validations before each `render` to ensure that you have all of the data you need in the right form before you try to use it.
+
+- - -
+
+Both of these features are entirely optional. We've found them to be increasingly valuable at Facebook as our applications grow and evolve, and we hope others find them useful as well.

docs/_posts/2013-07-17-react-v0-4-0.md

@@ -0,0 +1,40 @@
+---
+title: "React v0.4.0"
+layout: post
+author: Paul O'Shannessy
+---
+
+Over the past 2 months we've been taking feedback and working hard to make React even better. We fixed some bugs, made some under-the-hood improvements, and added several features that we think will improve the experience developing with React. Today we're proud to announce the availability of React v0.4!
+
+
+This release could not have happened without the support of our growing community. Since launch day, the community has contributed blog posts, questions to the [Google Group](http://groups.google.com/group/reactjs), and issues and pull requests on GitHub. We've had contributions ranging from documentation improvements to major changes to React's rendering. We've seen people integrate React into the tools they're using and the products they're building, and we're all very excited to see what our budding community builds next!
+
+React v0.4 has some big changes. We've also restructured the documentation to better communicate how to use React. We've summarized the changes below and linked to documentation where we think it will be especially useful.
+
+When you're ready, [go download it](/react/downloads.html)!
+
+
+### React
+
+* Switch from using `id` attribute to `data-reactid` to track DOM nodes. This allows you to integrate with other JS and CSS libraries more easily.
+* Support for more DOM elements and attributes (e.g., `<canvas>`)
+* Improved server-side rendering APIs. `React.renderComponentToString(<component>, callback)` allows you to use React on the server and generate markup which can be sent down to the browser.
+* `prop` improvements: validation and default values. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/11/react-v0-4-prop-validation-and-default-values.html)
+* Support for the `key` prop, which allows for finer control over reconciliation. [Read the docs for details...](http://facebook.github.io/react/docs/multiple-components.html)
+* Removed `React.autoBind`. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/02/react-v0-4-autobind-by-default.html)
+* Improvements to forms. We've written wrappers around `<input>`, `<textarea>`, `<option>`, and `<select>` in order to standardize many inconsistencies in browser implementations. This includes support for `defaultValue`, and improved implementation of the `onChange` event, and circuit completion. [Read the docs for details...](http://facebook.github.io/react/docs/forms.html)
+* We've implemented an improved synthetic event system that conforms to the W3C spec.
+* Updates to your component are batched now, which may result in a significantly faster re-render of components. `this.setState` now takes an optional callback as its second parameter. If you were using `onClick={this.setState.bind(this, state)}` previously, you'll want to make sure you add a third parameter so that the event is not treated as the callback.
+
+### JSX
+
+* Support for comment nodes `<div>{/* this is a comment and won't be rendered */}</div>`
+* Children are now transformed directly into arguments instead of being wrapped in an array
+  E.g. `<div><Component1/><Component2/></div>` is transformed into `React.DOM.div(null, Component1(null), Component2(null))`.
+  Previously this would be transformed into `React.DOM.div(null, [Component1(null), Component2(null)])`.
+  If you were using React without JSX previously, your code should still work.
+
+### react-tools
+
+* Fixed a number of bugs when transforming directories
+* No longer re-write `require()`s to be relative unless specified

docs/_posts/2013-07-23-community-roundup-5.md

@@ -0,0 +1,99 @@
+---
+title: "Community Round-up #5"
+layout: post
+author: Vjeux
+---
+
+We launched the [React Facebook Page](https://www.facebook.com/react) along with the React v0.4 launch. 700 people already liked it to get updated on the project :)
+
+## Cross-browser onChange
+
+[Ben Alpert](http://benalpert.com/) from [Khan Academy](https://www.khanacademy.org/) worked on a cross-browser implementation of `onChange` event that landed in v0.4. He wrote a blog post explaining the various browser quirks he had to deal with.
+
+> First off, what is the input event? If you have an `<input>` element and want to receive events whenever the value changes, the most obvious thing to do is to listen to the change event. Unfortunately, change fires only after the text field is defocused, rather than on each keystroke. The next obvious choice is the keyup event, which is triggered whenever a key is released. Unfortunately, keyup doesn't catch input that doesn't involve the keyboard (e.g., pasting from the clipboard using the mouse) and only fires once if a key is held down, rather than once per inserted character.
+>
+> Both keydown and keypress do fire repeatedly when a key is held down, but both fire immediately before the value changes, so to read the new value you have to defer the handler to the next event loop using `setTimeout(fn, 0)` or similar, which slows down your app. Of course, like keyup, neither keydown nor keypress fires for non-keyboard input events, and all three can fire in cases where the value doesn't change at all (such as when pressing the arrow keys).
+>
+> [Read the full post...](http://benalpert.com/2013/06/18/a-near-perfect-oninput-shim-for-ie-8-and-9.html)
+
+
+## React Samples
+
+Learning a new library is always easier when you have working examples you can play with. [jwh](https://github.com/jhw) put many of them on his [react-samples Github repo](https://github.com/jhw/react-samples).
+
+> Some simple examples with Facebook's React framework
+>
+> * Bootstrap action bar, modal and table [#1](https://rawgithub.com/jhw/react-samples/master/html/actionbar.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/bootstrap_actionbar.html),
+> [#3](https://rawgithub.com/jhw/react-samples/master/html/bootstrap_modal.html),
+> [#4](https://rawgithub.com/jhw/react-samples/master/html/bootstrap_striped_table.html)
+> * Comments [#1](https://rawgithub.com/jhw/react-samples/master/html/comments1.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/comments2.html)
+> * Data Table [#1](https://rawgithub.com/jhw/react-samples/master/html/datatable.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/datatable2.html),
+> [#3](https://rawgithub.com/jhw/react-samples/master/html/datatable3.html),
+> [#4](https://rawgithub.com/jhw/react-samples/master/html/datatable4.html),
+> [#5](https://rawgithub.com/jhw/react-samples/master/html/datatable5.html)
+> * Filter Bar [#1](https://rawgithub.com/jhw/react-samples/master/html/filterbar.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/filterbar2.html),
+> [#3](https://rawgithub.com/jhw/react-samples/master/html/filterbar3.html),
+> [#4](https://rawgithub.com/jhw/react-samples/master/html/filterbar4.html),
+> [#5](https://rawgithub.com/jhw/react-samples/master/html/filterbar5.html)
+> * Fundoo Rating [#1](https://rawgithub.com/jhw/react-samples/master/html/fundoo.html)
+> * Line Char: [#1](https://rawgithub.com/jhw/react-samples/master/html/linechart.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/linechart2.html)
+> * Multi tabs [#1](https://rawgithub.com/jhw/react-samples/master/html/multitabs.html)
+> * Select [#1](https://rawgithub.com/jhw/react-samples/master/html/select.html)
+> * Simple Tabs [#1](https://rawgithub.com/jhw/react-samples/master/html/simpletabs.html),
+> [#2](https://rawgithub.com/jhw/react-samples/master/html/simpletabs2.html),
+> [#3](https://rawgithub.com/jhw/react-samples/master/html/simpletabs3.html),
+> [#4](https://rawgithub.com/jhw/react-samples/master/html/simpletabs4.html)
+> * Toggle [#1](https://rawgithub.com/jhw/react-samples/master/html/toggle.html)
+
+
+## React Chosen Wrapper
+
+[Cheng Lou](https://github.com/chenglou) wrote a wrapper for the [Chosen](http://harvesthq.github.io/chosen/) input library called [react-chosen](https://github.com/chenglou/react-chosen). It took just 25 lines to be able to use jQuery component as a React one.
+
+```javascript
+React.renderComponent(
+  <Chosen noResultsText="No result" value="Harvest" onChange={doSomething}>
+    <option value="Facebook">Facebook</option>
+    <option value="Harvest">Harvest</option>
+  </Chosen>
+, document.body);
+```
+
+
+## JSX and ES6 Template Strings
+
+[Domenic Denicola](http://domenicdenicola.com/) wrote a slide deck about the great applications of ES6 features and one slide shows how we could use Template Strings to compile JSX at run-time without the need for a pre-processing phase.
+
+<figure><iframe src="http://www.slideshare.net/slideshow/embed_code/24187146?rel=0&startSlide=36" width="600" height="356" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" style="border:1px solid #CCC;border-width:1px 1px 0;margin-bottom:5px" allowfullscreen webkitallowfullscreen mozallowfullscreen> </iframe></figure>
+
+
+## React Presentation
+
+[Tom Occhino](http://tomocchino.com/) and [Jordan Walke](https://github.com/jordwalke), React developers, did a presentation of React at Facebook Seattle's office. Check out the first 25 minutes for the presentation and the remaining 45 for a Q&A. I highly recommend you watching this video.
+
+<figure><iframe width="650" height="400" src="//www.youtube.com/embed/XxVg_s8xAms" frameborder="0" allowfullscreen></iframe></figure>
+
+
+## Docs
+
+[Pete Hunt](http://www.petehunt.net/) rewrote the entirety of the docs for v0.4. The goal was to add more explanation about why we built React and what the best practices are.
+
+> Guides
+>
+> * [Why React?](/react/docs/why-react.html)
+> * [Displaying Data](/react/docs/displaying-data.html)
+>   * [JSX in Depth](/react/docs/jsx-in-depth.html)
+>   * [JSX Gotchas](/react/docs/jsx-gotchas.html)
+> * [Interactivity and Dynamic UIs](/react/docs/interactivity-and-dynamic-uis.html)
+> * [Multiple Components](/react/docs/multiple-components.html)
+> * [Reusable Components](/react/docs/reusable-components.html)
+> * [Forms](/react/docs/forms.html)
+> * [Working With the Browser](/react/docs/working-with-the-browser.html)
+>   * [More About Refs](/react/docs/more-about-refs.html)
+> * [Tooling integration](/react/docs/tooling-integration.html)
+> * [Reference](/react/docs/top-level-api.html)

docs/_posts/2013-07-26-react-v0-4-1.md

@@ -0,0 +1,25 @@
+---
+title: "React v0.4.1"
+layout: post
+author: Paul O'Shannessy
+---
+
+React v0.4.1 is a small update, mostly containing correctness fixes. Some code has been restructured internally but those changes do not impact any of our public APIs.
+
+
+## React
+
+* `setState` callbacks are now executed in the scope of your component.
+* `click` events now work on Mobile Safari.
+* Prevent a potential error in event handling if `Object.prototype` is extended.
+* Don't set DOM attributes to the string `"undefined"` on update when previously defined.
+* Improved support for `<iframe>` attributes.
+* Added checksums to detect and correct cases where server-side rendering markup mismatches what React expects client-side.
+
+
+## JSXTransformer
+
+* Improved environment detection so it can be run in a non-browser environment.
+
+
+[Download it now!](/react/downloads.html)

docs/_posts/2013-07-30-use-react-and-jsx-in-ruby-on-rails.md

@@ -0,0 +1,54 @@
+---
+title: "Use React and JSX in Ruby on Rails"
+layout: post
+author: Paul O'Shannessy
+---
+
+Today we're releasing a gem to make it easier to use React and JSX in Ruby on Rails applications: [react-rails](https://github.com/facebook/react-rails).
+
+
+This gem has 2 primary purposes:
+
+1. To package `react.js` in a way that's easy to use and easy to update.
+2. To allow you to write JSX without an external build step to transform that into JS.
+
+
+## Packaging react.js
+
+To make `react.js` available for use client-side, simply add `react` to your manifest, and declare the variant you'd like to use in your environment. When you use `:production`, the minified and optimized `react.min.js` will be used instead of the development version. For example:
+
+```ruby
+# config/environments/development.rb
+
+MyApp::Application.configure do
+  config.react.variant = :development
+  # use :production in production.rb
+end
+```
+
+```js
+// app/assets/javascript/application.js
+
+//= require react
+```
+
+
+## Writing JSX
+
+When you name your file with `myfile.js.jsx`, `react-rails` will automatically try to transform that file. For the time being, we still require that you include the docblock at the beginning of the file. For example, this file will get transformed on request.
+
+```js
+/** @jsx React.DOM */
+React.renderComponent(<MyComponent/>, document.body)
+```
+
+
+## Asset Pipeline
+
+`react-rails` takes advantage of the [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) that was introduced in Rails 3.1. A very important part of that pipeline is the `assets:precompile` Rake task. `react-rails` will ensure that your JSX files will be transformed into regular JS before all of your assets are minified and packaged.
+
+
+## Installation
+
+Installation follows the same process you're familiar with. You can install it globally with `gem install react-rails`, though we suggest you add the dependency to your `Gemfile` directly.
+

docs/_posts/2013-08-05-community-roundup-6.md

@@ -0,0 +1,80 @@
+---
+title: "Community Round-up #6"
+layout: post
+author: Vjeux
+---
+
+This is the first Community Round-up where none of the items are from Facebook/Instagram employees. It's great to see the adoption of React growing.
+
+## React Game Tutorial
+
+[Caleb Cassel](https://twitter.com/CalebCassel) wrote a [step-by-step tutorial](https://rawgithub.com/calebcassel/react-demo/master/part1.html) about making a small game. It covers JSX, State and Events, Embedded Components and Integration with Backbone.
+<figure>[![](/react/img/blog/dog-tutorial.png)](https://rawgithub.com/calebcassel/react-demo/master/part1.html)</figure>
+
+
+## Reactify
+
+[Andrey Popp](http://andreypopp.com/) created a [Browserify](http://browserify.org/) helper to compile JSX files.
+
+> Browserify v2 transform for `text/jsx`. Basic usage is:
+>
+> ```
+% browserify -t reactify main.jsx
+```
+>
+> `reactify` transform activates for files with either `.jsx` extension or `/** @jsx React.DOM */` pragma as a first line for any `.js` file.
+>
+> [Check it out on Github...](https://github.com/andreypopp/reactify)
+
+
+
+## React Integration with Este
+
+[Daniel Steigerwald](http://daniel.steigerwald.cz/) is now using React within [Este](https://github.com/steida/este), which is a development stack for web apps in CoffeeScript that are statically typed using the Closure Library.
+
+```coffeescript
+este.demos.react.todoApp = este.react.create (`/** @lends {React.ReactComponent.prototype} */`)
+  render: ->
+    @div [
+      este.demos.react.todoList 'items': @state['items']
+      if @state['items'].length
+        @p "#{@state['items'].length} items."
+      @form 'onSubmit': @onFormSubmit, [
+        @input
+          'onChange': @onChange
+          'value': @state['text']
+          'autoFocus': true
+          'ref': 'textInput'
+        @button "Add ##{@state['items'].length + 1}"
+      ]
+    ]
+```
+
+[Check it out on Github...](https://github.com/steida/este-library/blob/master/este/demos/thirdparty/react/start.coffee)
+
+
+## React Stylus Boilerplate
+
+[Zaim Bakar](http://zaim.github.io/) shared his boilerplate to get started with Stylus CSS processor.
+
+> This is my boilerplate React project using Grunt as the build tool, and Stylus as my CSS preprocessor.
+> 
+> - Very minimal HTML boilerplate
+> - Uses Stylus, with nib included
+> - Uses two build targets:
+>   - `grunt build` to compile JSX and Stylus into a development build
+>   - `grunt dist` to minify and optimize the development build for production
+>
+> [Check it out on Github...](https://github.com/zaim/react-stylus-boilerplate)
+
+
+## WebFUI
+
+[Conrad Barski](http://lisperati.com/), author of the popular book [Land of Lisp](http://landoflisp.com/), wants to use React for his ClojureScript library called [WebFUI](https://github.com/drcode/webfui).
+
+> I'm the author of "[Land of Lisp](http://landoflisp.com/)" and I love your framework. I built a somewhat similar framework a year ago [WebFUI](https://github.com/drcode/webfui) aimed at ClojureScript. My framework also uses global event delegates, a global "render" function, DOM reconciliation, etc just like react.js. (Of course these ideas all have been floating around the ether for ages, always great to see more people building on them.)
+>
+> Your implementation is more robust, and so I think the next point release of webfui will simply delegate all the "hard work" to react.js and will only focus on the areas where it adds value (enabling purely functional UI programming in clojurescript, and some other stuff related to streamlining event handling)
+<figure>[![](/react/img/blog/landoflisp.png)](https://groups.google.com/forum/#!msg/reactjs/e3bYersyd64/qODfcuBR9LwJ)</figure>
+>
+> [Read the full post...](https://groups.google.com/forum/#!msg/reactjs/e3bYersyd64/qODfcuBR9LwJ)

docs/_posts/2013-08-19-use-react-and-jsx-in-python-applications.md

@@ -0,0 +1,56 @@
+---
+title: "Use React and JSX in Python Applications"
+layout: post
+author: Kunal Mehta
+---
+
+Today we're happy to announce the initial release of [PyReact](https://github.com/facebook/react-python), which makes it easier to use React and JSX in your Python applications. It's designed to provide an API to transform your JSX files into JavaScript, as well as provide access to the latest React source files.
+
+## Usage
+
+Transform your JSX files via the provided `jsx` module:
+
+```python
+from react import jsx
+
+# For multiple paths, use the JSXTransformer class.
+transformer = jsx.JSXTransformer()
+for jsx_path, js_path in my_paths:
+    transformer.transform(jsx_path, js_path)
+
+# For a single file, you can use a shortcut method.
+jsx.transform('path/to/input/file.jsx', 'path/to/output/file.js')
+```
+
+For full paths to React files, use the `source` module:
+
+```python
+from react import source
+
+# path_for raises IOError if the file doesn't exist.
+react_js = source.path_for('react.min.js')
+```
+
+## Django
+
+PyReact includes a JSX compiler for [django-pipeline](https://github.com/cyberdelia/django-pipeline). Add it to your project's pipeline settings like this:
+
+```python
+PIPELINE_COMPILERS = (
+  'react.utils.pipeline.JSXCompiler',
+)
+```
+
+## Installation
+
+PyReact is hosted on PyPI, and can be installed with `pip`:
+
+    $ pip install PyReact
+
+Alternatively, add it into your `requirements` file:
+
+    PyReact==0.1.1
+
+**Dependencies**: PyReact uses [PyExecJS](https://github.com/doloopwhile/PyExecJS) to execute the bundled React code, which requires that a JS runtime environment is installed on your machine. We don't explicitly set a dependency on a runtime environment; Mac OS X comes bundled with one. If you're on a different platform, we recommend [PyV8](https://code.google.com/p/pyv8/).
+
+For the initial release, we've only tested on Python 2.7. Look out for support for Python 3 in the future, and if you see anything that can be improved, we welcome your [contributions](https://github.com/facebook/react-python/blob/master/CONTRIBUTING.md)!

docs/_posts/2013-08-26-community-roundup-7.md

@@ -0,0 +1,74 @@
+---
+title: "Community Round-up #7"
+layout: post
+author: Vjeux
+---
+
+It's been three months since we open sourced React and it is going well. Some stats so far:
+
+* 114 285 unique visitors on this website
+* [1933 stars](https://github.com/facebook/react/stargazers) and [210 forks](https://github.com/facebook/react/network/members)
+* [226 posts on Google Group](https://groups.google.com/forum/#!forum/reactjs)
+* [76 Github projects using React](https://gist.github.com/vjeux/6335762)
+* [30 contributors](https://github.com/facebook/react/graphs/contributors)
+* [15 blog posts](http://facebook.github.io/react/blog/)
+* 2 early adopters: [Khan Academy](http://benalpert.com/2013/06/09/using-react-to-speed-up-khan-academy.html) and [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/)
+
+
+## Wolfenstein Rendering Engine Ported to React
+
+[Pete Hunt](http://www.petehunt.net/) ported the render code of the web version of Wolfenstein 3D to React. Check out [the demo](http://www.petehunt.net/wolfenstein3D-react/wolf3d.html) and [render.js](https://github.com/petehunt/wolfenstein3D-react/blob/master/js/renderer.js#L183) file for the implementation.
+<figure>[![](/react/img/blog/wolfenstein_react.png)](http://www.petehunt.net/wolfenstein3D-react/wolf3d.html)</figure>
+
+
+## React & Meteor
+
+[Ben Newman](https://twitter.com/benjamn) made a [13-lines wrapper](https://github.com/benjamn/meteor-react/blob/master/lib/mixin.js) to use React and Meteor together. [Meteor](http://www.meteor.com/) handles the real-time data synchronization between client and server. React provides the declarative way to write the interface and only updates the parts of the UI that changed.
+
+> This repository defines a Meteor package that automatically integrates the React rendering framework on both the client and the server, to complement or replace the default Handlebars templating system.
+>
+> The React core is officially agnostic about how you fetch and update your data, so it is far from obvious which approach is the best. This package provides one answer to that question (use Meteor!), and I hope you will find it a compelling combination.
+>
+>```javascript
+>var MyComponent = React.createClass({
+>  mixins: [MeteorMixin],
+>
+>  getMeteorState: function() {
+>    return { foo: Session.get('foo') };
+>  },
+>
+>  render: function() {
+>    return <div>{this.state.foo}</div>;
+>  }
+>});
+>```
+>
+> Dependencies will be registered for any data accesses performed by getMeteorState so that the component can be automatically re-rendered whenever the data changes.
+>
+> [Read more ...](https://github.com/benjamn/meteor-react)
+
+## React Page
+
+[Jordan Walke](https://github.com/jordwalke) implemented a complete React project creator called [react-page](https://github.com/facebook/react-page/). It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload.
+
+> Easy Application Development with React JavaScript
+> <figure>[![](/react/img/blog/react-page.png)](https://github.com/facebook/react-page/)</figure>
+>
+> **Why Server Rendering?**
+>
+> * Faster initial page speed:
+>   * Markup displayed before downloading large JavaScript.
+>   * Markup can be generated more quickly on a fast server than low power client devices.
+> * Faster Development and Prototyping:
+>   * Instantly refresh your app without waiting for any watch scripts or bundlers.
+> * Easy deployment of static content pages/blogs: just archive using recursive wget.
+> * SEO benefits of indexability and perf.
+>
+> **How Does Server Rendering Work?**
+>
+> * `react-page` computes page markup on the server, sends it to the client so the user can see it quickly.
+> * The corresponding JavaScript is then packaged and sent.
+> * The browser runs that JavaScript, so that all of the event handlers, interactions and update code will run seamlessly on top of the server generated markup.
+> * From the developer's (and the user's) perspective, it's just as if the rendering occurred on the client, only faster.
+>
+> [Try it out ...](https://github.com/facebook/react-page/)

docs/_posts/2013-09-24-community-roundup-8.md

@@ -0,0 +1,70 @@
+---
+title: "Community Round-up #8"
+layout: post
+author: Vjeux
+---
+
+A lot has happened in the month since our last update. Here are some of the more interesting things we've found. But first, we have a couple updates before we share links.
+
+First, we are organizing a [React Hackathon](http://reactjshack-a-thon.splashthat.com/) in Facebook's Seattle office on Saturday September 28. If you want to hack on React, meet some of the team or win some prizes, feel free to join us!
+
+We've also reached a point where there are too many questions for us to handle directly. We're encouraging people to ask questions on [StackOverflow](http://stackoverflow.com/questions/tagged/reactjs) using the tag [[reactjs]](http://stackoverflow.com/questions/tagged/reactjs). Many members of the team and community have subscribed to the tag, so feel free to ask questions there. We think these will be more discoverable than Google Groups archives or IRC logs.
+
+## Javascript Jabber
+
+[Pete Hunt](http://www.petehunt.net/) and [Jordan Walke](https://github.com/jordwalke) were interviewed on [Javascript Jabber](http://javascriptjabber.com/073-jsj-react-with-pete-hunt-and-jordan-walke/) for an hour.  They go over many aspects of React such as 60 FPS, Data binding, Performance, Diffing Algorithm, DOM Manipulation, Node.js support, server-side rendering, JSX, requestAnimationFrame and the community. This is a gold mine of information about React.
+
+> **PETE:**  So React was designed all around that. Conceptually, how you build a React app is that every time your data changes, it's like hitting the refresh button in a server-rendered app. What we do is we conceptually throw out all of the markup and event handlers that you've registered and we reset the whole page and then we redraw the entire page. If you're writing a server-rendered app, handling updates is really easy because you hit the refresh button and you're pretty much guaranteed to get what you expect.
+>
+> **MERRICK:**  That's true. You don't get into these odd states.
+>
+> **PETE:**  Exactly, exactly. In order to implement that, we communicate it as a fake DOM. What we'll do is rather than throw out the actual browser html and event handlers, we have an internal representation of what the page looks like and then we generate a brand new representation of what we want the page to look like. Then we perform this really, really fast diffing algorithm between those two page representations, DOM representations. Then React will compute the minimum set of DOM mutations it needs to make to bring the page up to date.
+>
+> Then to finally get to answer your question, that set of DOM mutations then goes into a queue and we can plug in arbitrary flushing strategies for that. For example, when we originally launched React in open source, every setState would immediately trigger a flush to the DOM. That wasn't part of the contract of setState, but that was just our strategy and it worked pretty well. Then this totally awesome open source contributor Ben Alpert at Khan Academy built a new batching strategy which would basically queue up every single DOM update and state change that happened within an event tick and would execute them in bulk at the end of the event tick.
+>
+> [Read the full conversation ...](http://javascriptjabber.com/073-jsj-react-with-pete-hunt-and-jordan-walke/)
+
+
+## JSXTransformer Trick
+
+While this is not going to work for all the attributes since they are camelCased in React, this is a pretty cool trick.
+
+<div style="margin-left: 74px;"><blockquote class="twitter-tweet"><p>Turn any DOM element into a React.js function: JSXTransformer.transform(&quot;/** <a href="https://twitter.com/jsx">@jsx</a> React.DOM */&quot; + element.innerHTML).code</p>&mdash; Ross Allen (@ssorallen) <a href="https://twitter.com/ssorallen/statuses/377105575441489920">September 9, 2013</a></blockquote></div>
+<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
+
+
+## Remarkable React
+
+[Stoyan Stefanov](http://www.phpied.com/) gave a talk at [BrazilJS](http://braziljs.com.br/) about React and wrote an article with the content of the presentation. He goes through the difficulties of writting _active apps_ using the DOM API and shows how React handles it.
+
+> So how does exactly React deal with it internally? Two crazy ideas - virtual DOM and synthetic events.
+>
+> You define you components in React. It builds a virtual DOM in JavaScript land which is way more efficient. Then it updates the DOM. (And "virtual DOM" is a very big name for what is simply a JavaScript object with nested key-value pairs)
+>
+> Data changes. React computes a diff (in JavaScript land, which is, of course, much more efficient) and updates the single table cell that needs to change. React replicates the state of the virtual DOM into the actual DOM only when and where it's necessary. And does it all at once, in most cases in a single tick of the `requestAnimationFrame()`.
+>
+> What about event handlers? They are synthetic. React uses event delegation to listen way at the top of the React tree. So removing a node in the virtual DOM has no effect on the event handling.
+>
+> The events are automatically cross-browser (they are React events). They are also much closer to W3C than any browser. That means that for example `e.target` works, no need to look for the event object or checking whether it's `e.target` or `e.srcElement` (IE). Bubbling and capturing phases also work cross browser. React also takes the liberty of making some small fixes, e.g. the event `<input onChange>` fires when you type, not when blur away from the input. And of course, event delegation is used as the most efficient way to handle events. You know that "thou shall use event delegation" is also commonly given advice for making web apps snappy.
+>
+> The good thing about the virtual DOM is that it's all in JavaScript land. You build all your UI in JavaScript. Which means it can be rendered on the server side, so you initial view is fast (and any SEO concerns are addressed). Also, if there are especially heavy operations they can be threaded into WebWorkers, which otherwise have no DOM access.
+>
+> [Read More ...](http://www.phpied.com/remarkable-react/)
+
+
+## Markdown in React
+
+[Ben Alpert](http://benalpert.com/) converted [marked](https://github.com/chjj/marked), a Markdown Javascript implementation, in React: [marked-react](https://github.com/spicyj/marked-react). Even without using JSX, the HTML generation is now a lot cleaner. It is also safer as forgetting a call to `escape` will not introduce an XSS vulnerability.
+<figure>[![](/react/img/blog/markdown_refactor.png)](https://github.com/spicyj/marked-react/commit/cb70c9df6542c7c34ede9efe16f9b6580692a457)</figure>
+
+
+## Unite from BugBusters
+
+[Renault John Lecoultre](https://twitter.com/renajohn) wrote [Unite](https://www.bugbuster.com/), an interactive tool for analyzing code dynamically using React. It integrates with CodeMirror.
+<figure>[![](/react/img/blog/unite.png)](https://unite.bugbuster.com/)</figure>
+
+## #reactjs IRC Logs
+
+[Vjeux](http://blog.vjeux.com/) re-implemented the display part of the IRC logger in React. Just 130 lines are needed for a performant infinite scroll with timestamps and color-coded author names.
+
+<iframe width="100%" height="300" src="http://jsfiddle.net/vjeux/QL9tz/embedded/" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

docs/_posts/2013-10-16-react-v0.5.0.md

@@ -0,0 +1,52 @@
+---
+title: "React v0.5"
+layout: post
+author: Paul O'Shannessy
+---
+
+This release is the result of several months of hard work from members of the team and the community. While there are no groundbreaking changes in core, we've worked hard to improve performance and memory usage. We've also worked hard to make sure we are being consistent in our usage of DOM properties.
+
+The biggest change you'll notice as a developer is that we no longer support `class` in JSX as a way to provide CSS classes. Since this prop was being converted to `className` at the transform step, it caused some confusion when trying to access it in composite components. As a result we decided to make our DOM properties mirror their counterparts in the JS DOM API. There are [a few exceptions](https://github.com/facebook/react/blob/master/src/dom/DefaultDOMPropertyConfig.js#L156) where we deviate slightly in an attempt to be consistent internally.
+
+The other major change in v0.5 is that we've added an additional build - `react-with-addons` - which adds support for some extras that we've been working on including animations and two-way binding. [Read more about these addons in the docs](/react/docs/addons.html).
+
+## Thanks to Our Community
+
+We added *22 new people* to the list of authors since we launched React v0.4.1 nearly 3 months ago. With a total of 48 names in our `AUTHORS` file, that means we've nearly doubled the number of contributors in that time period. We've seen the number of people contributing to discussion on IRC, mailing lists, Stack Overflow, and GitHub continue rising. We've also had people tell us about talks they've given in their local community about React.
+
+It's been awesome to see the things that people are building with React, and we can't wait to see what you come up with next!
+
+
+## Changelog
+
+### React
+
+* Memory usage improvements - reduced allocations in core which will help with GC pauses
+* Performance improvements - in addition to speeding things up, we made some tweaks to stay out of slow path code in V8 and Nitro.
+* Standardized prop -> DOM attribute process. This previously resulting in additional type checking and overhead as well as confusing cases for users. Now we will always convert your value to a string before inserting it into the DOM.
+* Support for Selection events.
+* Support for [Composition events](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent).
+* Support for additional DOM properties (`charSet`, `content`, `form`, `httpEquiv`, `rowSpan`, `autoCapitalize`).
+* Support for additional SVG properties (`rx`, `ry`).
+* Support for using `getInitialState` and `getDefaultProps` in mixins.
+* Support mounting into iframes.
+* Bug fixes for controlled form components.
+* Bug fixes for SVG element creation.
+* Added `React.version`.
+* Added `React.isValidClass` - Used to determine if a value is a valid component constructor.
+* Removed `React.autoBind` - This was deprecated in v0.4 and now properly removed.
+* Renamed  `React.unmountAndReleaseReactRootNode` to `React.unmountComponentAtNode`.
+* Began laying down work for refined performance analysis.
+* Better support for server-side rendering - [react-page](https://github.com/facebook/react-page) has helped improve the stability for server-side rendering.
+* Made it possible to use React in environments enforcing a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Security/CSP/Introducing_Content_Security_Policy). This also makes it possible to use React to build Chrome extensions.
+
+### React with Addons (New!)
+
+* Introduced a separate build with several "addons" which we think can help improve the React experience. We plan to deprecate this in the long-term, instead shipping each as standalone pieces. [Read more in the docs](/react/docs/addons.html).
+
+### JSX
+
+* No longer transform `class` to `className` as part of the transform! This is a breaking change - if you were using `class`, you *must* change this to `className` or your components will be visually broken.
+* Added warnings to the in-browser transformer to make it clear it is not intended for production use.
+* Improved compatibility for Windows
+* Improved support for maintaining line numbers when transforming.

docs/_posts/2013-10-3-community-roundup-9.md

@@ -0,0 +1,100 @@
+---
+title: "Community Round-up #9"
+layout: post
+author: Vjeux
+---
+
+We organized a React hackathon last week-end in the Facebook Seattle office. 50 people, grouped into 15 teams, came to hack for a day on React. It was a lot of fun and we'll probably organize more in the future.
+
+![](/react/img/blog/react-hackathon.jpg)
+
+
+## React Hackathon Winner
+
+[Alex Swan](http://bold-it.com/) implemented [Qu.izti.me](http://qu.izti.me/), a multi-player quiz game. It is real-time via Web Socket and mobile friendly.
+
+> The game itself is pretty simple. People join the "room" by going to [http://qu.izti.me](http://qu.izti.me/) on their device. Large displays will show a leaderboard along with the game, and small displays (such as phones) will act as personal gamepads. Users will see questions and a choice of answers. The faster you answer, the more points you earn.
+>
+> In my opinion, Socket.io and React go together like chocolate and peanut butter. The page was always an accurate representation of the game object.
+><figure>[![](/react/img/blog/quiztime.png)](http://bold-it.com/javascript/facebook-react-example/)</figure>
+>
+> [Read More...](http://bold-it.com/javascript/facebook-react-example/)
+
+## JSConf EU Talk: Rethinking Best Practices
+
+[Pete Hunt](http://www.petehunt.net/) presented React at JSConf EU. He covers three controversial design decisions of React:
+
+1. Build **components**, not templates
+2. Re-render the whole app on every update
+3. Virtual DOM
+
+The video will be available soon on the [JSConf EU website](http://2013.jsconf.eu/speakers/pete-hunt-react-rethinking-best-practices.html), but in the meantime, here are Pete's slides:
+
+<figure><iframe src="http://www.slideshare.net/slideshow/embed_code/26589373" width="550" height="450" frameborder="0" marginwidth="0" marginheight="0" scrolling="no" allowfullscreen></iframe></figure>
+
+
+## Pump - Clojure bindings for React
+
+[Alexander Solovyov](http://solovyov.net/) has been working on React bindings for ClojureScript. This is really exciting as it is using "native" ClojureScript data structures.
+
+```ruby
+(ns your.app
+  (:require-macros [pump.def-macros :refer [defr]])
+  (:require [pump.core]))
+
+(defr Component
+  :get-initial-state #(identity {:some-value ""})
+
+  [component props state]
+
+  [:div {:class-name "test"} "hello"])
+```
+
+[Check it out on GitHub...](https://github.com/piranha/pump)
+
+
+## JSXHint
+
+[Todd Kennedy](http://blog.selfassembled.org/) working at [Cond&eacute; Nast](http://www.condenast.com/) implemented a wrapper on-top of [JSHint](http://www.jshint.com/) that first converts JSX files to JS.
+
+> A wrapper around JSHint to allow linting of files containg JSX syntax. Accepts glob patterns. Respects your local .jshintrc file and .gitignore to filter your glob patterns.
+>
+> ```
+npm install -g jsxhint
+```
+>
+> [Check it out on GitHub...](https://github.com/CondeNast/JSXHint)
+
+
+## Turbo React
+
+[Ross Allen](https://twitter.com/ssorallen) working at [Mesosphere](http://mesosphere.io/) combined [Turbolinks](https://github.com/rails/turbolinks/), a library used by Ruby on Rails to speed up page transition, and React.
+
+> "Re-request this page" is just a link to the current page. When you click it, Turbolinks intercepts the GET request and fetchs the full page via XHR.
+>
+> The panel is rendered with a random panel- class on each request, and the progress bar gets a random widthX class.
+>
+> With Turbolinks alone, the entire <body> would be replaced, and transitions would not happen. In this little demo though, React adds and removes classes and text, and the attribute changes are animated with CSS transitions. The DOM is otherwise left intact.
+><figure>[![](/react/img/blog/turboreact.png)](https://turbo-react.herokuapp.com/)</figure>
+>
+> [Check out the demo...](https://turbo-react.herokuapp.com/)
+
+
+## Reactive Table
+
+[Stoyan Stefanov](http://www.phpied.com/) continues his series of blog posts about React. This one is an introduction tutorial on rendering a simple table with React.
+
+> React is all about components. So let's build one.
+>
+> Let's call it Table (to avoid any confusion what the component is about).
+>
+> ```javascript
+var Table = React.createClass({
+  /*stuff goeth here*/
+});
+```
+>
+> You see that React components are defined using a regular JS object. Some properties and methods of the object such as render() have special meanings, the rest is upforgrabs.
+>
+> [Read the full article...](http://www.phpied.com/reactive-table/)
+

docs/blog/all.html

@@ -0,0 +1,15 @@
+---
+title: Blog
+layout: default
+sectionid: blog
+id: all-posts
+---
+
+<section class="content wrap documentationContent nosidebar">
+  <div class="inner-content">
+    <h1>All Posts</h1>
+    {% for page in site.posts %}
+      <p><strong><a href="/react{{ page.url }}">{{ page.title }}</a></strong> on {{ page.date | date: "%B %e, %Y" }} by {{ page.author }}</p>
+    {% endfor %}
+  </div>
+</section>

docs/blog/index.html

@@ -4,25 +4,31 @@ layout: default
 sectionid: blog
 ---
 
-<section class="content wrap documentationContent">
+<section class="content wrap blogContent">
   {% include nav_blog.html %}
   <div class="inner-content">
-    {% for page in site.posts %}
+    {% for page in paginator.posts %}
       <div class="post-list-item">
         <h1><a href="/react{{ page.url }}">{{ page.title }}</a></h1>
         <p class="meta">{{ page.date | date: "%B %e, %Y" }} by {{ page.author }}</p>
-
-        <hr>
-
+        <hr />
         <div class="post">
-         {{ page.excerpt }}
-         {% if page.excerpt != page.content %}
-           <p>
-             <a href="/react{{ page.url }}">Continue Reading &rarr;</a>
-          </p>
-         {% endif %}
+         {{ page.content }}
         </div>
       </div>
     {% endfor %}
+
+    <div class="pagination">
+      {% if paginator.previous_page %}
+        <a href="/react/blog/{{ paginator.previous_page_path }}" class="previous">
+          &laquo; Previous Page
+        </a>
+      {% endif %}
+      {% if paginator.next_page %}
+        <a href="/react/blog/{{ paginator.next_page_path }}" class="next">
+          Next Page &raquo;
+        </a>
+      {% endif %}
+    </div>
   </div>
 </section>

docs/docs/01-why-react.md

@@ -0,0 +1,30 @@
+---
+id: why-react
+title: Why React?
+layout: docs
+permalink: why-react.html
+next: displaying-data.html
+---
+React is a JavaScript library for creating user interfaces by Facebook and Instagram. Many people choose to think of React as the **V** in **[MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)**.
+
+We built React to solve one problem: **building large applications with data that changes over time**. To do this, React uses two main ideas.
+
+### Simple
+
+Simply express how your app should look at any given point in time, and React will automatically manage all UI updates when your underlying data changes.
+
+### Declarative
+
+When the data changes, React conceptually hits the "refresh" button, and knows to only update the changed parts.
+
+## Build Composable Components
+
+React is all about building reusable components. In fact, with React the *only* thing you do is build components. Since they're so encapsulated, components make code reuse, testing, and separation of concerns easy.
+
+## Give It Five Minutes
+
+React challenges a lot of conventional wisdom, and at first glance some of the ideas may seem crazy. [Give it five minutes](http://37signals.com/svn/posts/3124-give-it-five-minutes) while reading this guide; those crazy ideas have worked for building thousands of components both inside and outside of Facebook and Instagram.
+
+## Learn More
+
+You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).

docs/docs/02-displaying-data.md

@@ -0,0 +1,91 @@
+---
+id: displaying-data
+title: Displaying Data
+layout: docs
+permalink: displaying-data.html
+prev: why-react.html
+next: jsx-in-depth.html
+---
+
+The most basic thing you can do with a UI is display some data. React makes it easy to display data and automatically keeps the interface up-to-date when the data changes.
+
+
+## Getting Started
+
+Let's look at a really simple example. Create a `hello-react.html` file with the following code:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Hello React</title>
+    <script src="http://fb.me/react-{{site.react_version}}.min.js"></script>
+    <script src="http://fb.me/JSXTransformer-{{site.react_version}}.js"></script>
+  </head>
+  <body>
+    <div id="example"></div>
+    <script type="text/jsx">
+
+      // ** Your code goes here! **
+
+    </script>
+  </body>
+</html>
+```
+
+For the rest of the documentation, we'll just focus on the JavaScript code and assume it's inserted into a template like the one above. Replace the placeholder comment above with the following JS:
+
+```javascript
+/** @jsx React.DOM */
+
+var HelloWorld = React.createClass({
+  render: function() {
+    return (
+      <p>
+        Hello, <input type="text" placeholder="Your name here" />!
+        It is {this.props.date.toTimeString()}
+      </p>
+    );
+  }
+});
+
+setInterval(function() {
+  React.renderComponent(
+    <HelloWorld date={new Date()} />,
+    document.getElementById('example')
+  );
+}, 500);
+```
+
+
+## Reactive Updates
+
+Open `hello-react.html` in a web browser and type your name into the text field. Notice that React is only changing the time string in the UI — any input you put in the text field remains, even though you haven't written any code to manage this behavior. React figures it out for you and does the right thing.
+
+The way we are able to figure this out is that React does not manipulate the DOM unless it needs to. **It uses a fast, internal mock DOM to perform diffs and computes the most efficient DOM mutation for you.**
+
+The inputs to this component are called `props` — short for "properties". They're passed as attributes in JSX syntax. You should think of these as immutable within the component, that is, **never write to `this.props`**.
+
+
+## Components are Just Like Functions
+
+React components are very simple. You can think of them as simple function that take in `props` and `state` (discussed later) and render HTML. Because they're so simple, it makes them very easy to reason about.
+
+> Note:
+>
+> **One limitation**: React components can only render a single root node. If you want to return multiple nodes they *must* be wrapped in a single root.
+
+
+## JSX Syntax
+
+We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.
+
+We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a very simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.
+
+**JSX lets you write JavaScript function calls with HTML syntax.** To generate a link in React using pure JavaScript you'd write: `React.DOM.a({href: 'http://facebook.github.io/react/'}, 'Hello React!')`. With JSX this becomes `<a href="http://facebook.github.io/react/">Hello React!</a>`. We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
+
+JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](./jsx-in-depth.html). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
+
+JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./jsx-gotchas.html) for some key differences.
+
+The easiest way to get started with JSX is to use the in-browser `JSXTransformer`. We strongly recommend that you don't use this in production. You can precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.

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

@@ -1,18 +1,17 @@
 ---
-id: docs-syntax
-title: JSX Syntax
-description: Writing JavaScript with XML syntax.
+id: jsx-in-depth
+title: JSX in Depth
 layout: docs
-prev: common-questions.html
-next: component-basics.html
+permalink: jsx-in-depth.html
+prev: displaying-data.html
+next: jsx-gotchas.html
 ---
 
-JSX is a JavaScript XML syntax transform recommended (but not required) for use
+JSX is a JavaScript XML syntax transform recommended for use
 with React.
 
-## Why JSX?
 
-First of all, **don't use JSX if you don't like it!**
+## Why JSX?
 
 React works out of the box without JSX. Simply construct your markup using the
 functions on `React.DOM`. For example, here's how to construct a simple link:
@@ -23,21 +22,22 @@ var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');
 
 We recommend using JSX for many reasons:
 
-- It's easier to visualize the structure of the DOM.
-- Designers are more comfortable making changes.
-- It's familiar for those who have used MXML or XAML.
+* It's easier to visualize the structure of the DOM.
+* Designers are more comfortable making changes.
+* It's familiar for those who have used MXML or XAML.
+
 
 ## The Transform
 
-JSX transforms XML-like syntax into native JavaScript. It turns XML elements and
-attributes into function calls and objects, respectively.
+JSX transforms from an XML-like syntax into native JavaScript. XML elements and
+attributes are transformed into function calls and objects, respectively.
 
 ```javascript
 var Nav;
 // Input (JSX):
 var app = <Nav color="blue" />;
 // Output (JS):
-var app = Nav({color:'blue'});
+var app = Nav({color:"blue"});
 ```
 
 Notice that in order to use `<Nav />`, the `Nav` variable must be in scope.
@@ -49,11 +49,11 @@ var Nav, Profile;
 // Input (JSX):
 var app = <Nav color="blue"><Profile>click</Profile></Nav>;
 // Output (JS):
-var app = Nav({color:'blue'}, Profile({}, 'click'));
+var app = Nav({color:"blue"}, Profile(null, "click"));
 ```
 
 Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it
-desguars into native JavaScript.
+desugars into native JavaScript.
 
 If you want to use JSX, the [Getting Started](getting-started.html) guide shows
 how to setup compilation.
@@ -63,16 +63,17 @@ how to setup compilation.
 > Details about the code transform are given here to increase understanding, but
 > your code should not rely on these implementation details.
 
+
 ## React and JSX
 
 React and JSX are independent technologies, but JSX was primarily built with
 React in mind. The two valid uses of JSX are:
 
-- To construct instances of React DOM components (`React.DOM.*`).
-- To construct instances of composite components created with
+* To construct instances of React DOM components (`React.DOM.*`).
+* To construct instances of composite components created with
   `React.createClass()`.
 
-**React DOM Components**
+### React DOM Components
 
 To construct a `<div>` is to create a variable that refers to `React.DOM.div`.
 
@@ -81,7 +82,7 @@ var div = React.DOM.div;
 var app = <div className="appClass">Hello, React!</div>;
 ```
 
-**React Component Components**
+### React Composite Components
 
 To construct an instance of a composite component, create a variable that
 references the class.
@@ -91,7 +92,7 @@ var MyComponent = React.createClass({/*...*/});
 var app = <MyComponent someProperty={true} />;
 ```
 
-See [Component Basics](component-basics.html) to learn more about components.
+See [Multiple Components](multiple-components.html) to learn more about using composite components.
 
 > Note:
 >
@@ -114,7 +115,7 @@ var Nav;
 // Input (JSX):
 var tree = <Nav><span /></Nav>;
 // Output (JS):
-var tree = Nav({}, React.DOM.span({}));
+var tree = Nav(null, React.DOM.span(null));
 ```
 
 > Remember:
@@ -125,7 +126,7 @@ var tree = Nav({}, React.DOM.span({}));
 
 ## JavaScript Expressions
 
-#### Attribute Expressions
+### Attribute Expressions
 
 To use a JavaScript expression as an attribute value, wrap the expression in a
 pair of curly braces (`{}`) instead of quotes (`""`).
@@ -137,7 +138,7 @@ var person = <Person name={window.isLoggedIn ? window.name : ''} />;
 var person = Person({name: window.isLoggedIn ? window.name : ''});
 ```
 
-#### Child Expressions
+### Child Expressions
 
 Likewise, JavaScript expressions may be used to express children:
 
@@ -145,24 +146,39 @@ Likewise, JavaScript expressions may be used to express children:
 // Input (JSX):
 var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;
 // Output (JS):
-var content = Container({}, window.isLoggedIn ? <Nav /> : <Login />);
+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:
+
+```javascript
+var content = <Container>{/* this is a comment */}<Nav /></Container>;
 ```
 
 ## Tooling
 
 Beyond the compilation step, JSX does not require any special tools.
 
-- Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
-- Linting provides accurate line numbers after compiling without sourcemaps.
-- Elements use standard scoping so linters can find usage of out-of-scope
+* Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
+  * JSX syntax highlighting is available for Sublime Text and other editors
+    that support `*.tmLanguage` using the third-party
+    [`JavaScript (JSX).tmLanguage`][1].
+* Linting provides accurate line numbers after compiling without sourcemaps.
+* Elements use standard scoping so linters can find usage of out-of-scope
   components.
 
+[1]: https://github.com/yungsters/sublime/blob/master/tmLanguage/JavaScript%20(JSX).tmLanguage
+
 ## Prior Work
 
 JSX is similar to several other JavaScript embedded XML language
 proposals/projects. Some of the features of JSX that distinguish it from similar
 efforts include:
 
-- JSX is a simple syntactic transform.
-- JSX neither provides nor requires a runtime library.
-- JSX does not alter or add to the semantics of JavaScript.
+* JSX is a simple syntactic transform.
+* JSX neither provides nor requires a runtime library.
+* JSX does not alter or add to the semantics of JavaScript.
+
+JSX is similar to HTML, but not exactly the same. See [JSX gotchas](./jsx-gotchas.html) for some key differences.

docs/docs/02.2-jsx-gotchas.md

@@ -0,0 +1,80 @@
+---
+id: jsx-gotchas
+title: JSX Gotchas
+layout: docs
+permalink: jsx-gotchas.html
+prev: jsx-in-depth.html
+next: interactivity-and-dynamic-uis.html
+---
+
+JSX looks like HTML but there are some important differences you may run into.
+
+> Note:
+>
+> For DOM differences, such as the inline `style` attribute, check [here](dom-differences.html).
+
+## Whitespace Removal
+
+JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes all whitespace between two curly braces expressions. If you want to have whitespace, simply add `{' '}`.
+
+```javascript
+<div>{this.props.name} {' '} {this.props.surname}</div>
+```
+
+Follow [Issue #65](https://github.com/facebook/react/issues/65) for discussion on this behavior.
+
+
+## HTML Entities
+
+You can insert HTML entities within literal text in JSX:
+
+```javascript
+<div>First &middot; Second</div>
+```
+
+If you want to display an HTML entity within dynamic content, you will run into double escaping issues as React escapes all the strings you are displaying in order to prevent a wide range of XSS attacks by default.
+
+```javascript
+// Bad: It displays "First &middot; Second"
+<div>{'First &middot; Second'}</div>
+```
+
+There are various ways to work-around this issue. The easiest one is to write unicode character directly in Javascript. You need to make sure that the file is saved as UTF-8 and that the proper UTF-8 directives are set so the browser will display it correctly.
+
+```javascript
+<div>{'First · Second'}</div>
+```
+
+A safer alternative is to find the [unicode number corresponding to the entity](http://www.fileformat.info/info/unicode/char/b7/index.htm) and use it inside of a JavaScript string.
+
+```javascript
+<div>{'First \u00b7 Second'}</div>
+<div>{'First ' + String.fromCharCode(183) + ' Second'}</div>
+```
+
+You can use mixed arrays with strings and JSX elements.
+
+```javascript
+<div>{['First ', <span>&middot;</span>, ' Second']}</div>
+```
+
+As a last resort, you always have the ability to insert raw HTML.
+
+```javascript
+<div dangerouslySetInnerHTML={{'{{'}}__html: 'First &middot; Second'}} />
+```
+
+
+## Custom HTML Attributes
+
+If you pass properties to native HTML elements that do not exist in the HTML specification, React will not render them. If you want to use a custom attribute, you should prefix it with `data-`.
+
+```javascript
+<div data-custom-attribute="foo" />
+```
+
+[Web Accessibility](http://www.w3.org/WAI/intro/aria) attributes starting with `aria-` will be rendered properly.
+
+```javascript
+<div aria-hidden={true} />
+```

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

@@ -0,0 +1,89 @@
+---
+id: interactivity-and-dynamic-uis
+title: Interactivity and Dynamic UIs
+layout: docs
+permalink: interactivity-and-dynamic-uis.html
+prev: jsx-gotchas.html
+next: multiple-components.html
+---
+
+You've already [learned how to display data](./displaying-data.html) with React. Now let's look at how to make our UIs interactive.
+
+
+## A Simple Example
+
+```javascript
+/** @jsx React.DOM */
+
+var LikeButton = React.createClass({
+  getInitialState: function() {
+    return {liked: false};
+  },
+  handleClick: function(event) {
+    this.setState({liked: !this.state.liked});
+  },
+  render: function() {
+    var text = this.state.liked ? 'like' : 'unlike';
+    return (
+      <p onClick={this.handleClick}>
+        You {text} this. Click to toggle.
+      </p>
+    );
+  }
+});
+
+React.renderComponent(
+  <LikeButton />,
+  document.getElementById('example')
+);
+```
+
+
+## Event Handling and Synthetic Events
+
+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.
+
+
+## Under the Hood: autoBind and Event Delegation
+
+Under the hood React does a few things to keep your code performant and easy to understand.
+
+**Autobinding:** When creating callbacks in JavaScript you usually need to explicitly bind a method to its instance such that the value of `this` is correct. With React, every method is automatically bound to its component instance. React caches the bound method such that it's extremely CPU and memory efficient. It's also less typing!
+
+**Event delegation:** React doesn't actually attach event handlers to the nodes themselves. When React starts up, it starts listening for all events at the top level using a single event listener. When a component is mounted or unmounted, the event handlers are simply added or removed from an internal mapping. When an event occurs, React knows how to dispatch it using this mapping. When there are no event handlers left in the mapping, React's event handlers are simple no-ops. To learn more about why this is fast, see [David Walsh's excellent blog post](http://davidwalsh.name/event-delegate).
+
+
+## Components are Just State Machines
+
+React thinks of UIs as simple state machines. By thinking of a UI as being in various states and rendering those states, it's easy to keep your UI consistent.
+
+In React, you simply update a component's state, and then render a new UI based on this new state. React takes care of updating the DOM for you in the most efficient way.
+
+
+## How State Works
+
+A common way to inform React of a data change is by calling `setState(data, callback)`. This method merges `data` into `this.state` and re-renders the component. When the component finishes re-rendering, the optional `callback` is called. Most of the time you'll never need to provide a `callback` since React will take care of keeping your UI up-to-date for you.
+
+
+## What Components Should Have State?
+
+Most of your components should simply take some data from `props` and render it. However, sometimes you need to respond to user input, a server request or the passage of time. For this you use state.
+
+**Try to keep as many of your components as possible stateless.** By doing this you'll isolate the state to its most logical place and minimize redundancy, making it easier to reason about your application.
+
+A common pattern is to create several stateless components that just render data, and have a stateful component above them in the hierarchy that passes its state to its children via `props`. The stateful component encapsulates all of the interaction logic, while the stateless components take care of rendering data in a declarative way.
+
+
+## What *Should* Go in State?
+
+**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?
+
+`this.state` should only contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:
+
+* **Computed data:** Don't worry about precomputing values based on state — it's easier to ensure that your UI is consistent if you do all computation within `render()`. For example, if you have an array of list items in state and you want to render the count as a string, simply render `this.state.listItems.length + ' list items'` in your `render()` method rather than storing it on state.
+* **React components:** Build them in `render()` based on underlying props and state.
+* **Duplicated data from props:** Try to use props as the source of truth where possible. Because props can change over time, it's appropriate to store props in state to be able to know its previous values.

docs/docs/04-multiple-components.md

@@ -0,0 +1,151 @@
+---
+id: multiple-components
+title: Multiple Components
+layout: docs
+permalink: multiple-components.html
+prev: interactivity-and-dynamic-uis.html
+next: reusable-components.html
+---
+
+So far, we've looked at how to write a single component to display data and handle user input. Next let's examine one of React's finest features: composability.
+
+
+## Motivation: Separation of Concerns
+
+By building modular components that reuse other components with well-defined interfaces, you get much of the same benefits that you get by using functions or classes. Specifically you can *separate the different concerns* of your app however you please simply by building new components. By building a custom component library for your application, you are expressing your UI in a way that best fits your domain.
+
+
+## Composition Example
+
+Let's create a simple Avatar component which shows a profile picture and username using the Facebook Graph API.
+
+```javascript
+/** @jsx React.DOM */
+
+var Avatar = React.createClass({
+  render: function() {
+    return (
+      <div>
+        <ProfilePic username={this.props.username} />
+        <ProfileLink username={this.props.username} />
+      </div>
+    );
+  }
+});
+
+var ProfilePic = React.createClass({
+  render: function() {
+    return (
+      <img src={'http://graph.facebook.com/' + this.props.username + '/picture'} />
+    );
+  }
+});
+
+var ProfileLink = React.createClass({
+  render: function() {
+    return (
+      <a href={'http://www.facebook.com/' + this.props.username}>
+        {this.props.username}
+      </a>
+    );
+  }
+});
+
+React.renderComponent(
+  <Avatar username="pwh" />,
+  document.getElementById('example')
+);
+```
+
+
+## Ownership
+
+In the above example, instances of `Avatar` *own* instances of `ProfilePic` and `ProfileLink`. In React, **an owner is the component that sets the `props` of other components**. More formally, if a component `X` is created in component `Y`'s `render()` method, it is said that `X` is *owned by* `Y`. As discussed earlier, a component cannot mutate its `props` — they are always consistent with what its owner sets them to. This key property leads to UIs that are guaranteed to be consistent.
+
+It's important to draw a distinction between the owner-ownee relationship and the parent-child relationship. The owner-ownee relationship is specific to React, while the parent-child relationship is simply the one you know and love from the DOM. In the example above, `Avatar` owns the `div`, `ProfilePic` and `ProfileLink` instances, and `div` is the **parent** (but not owner) of the `ProfilePic` and `ProfileLink` instances.
+
+
+## Children
+
+When you create a React component instance, you can include additional React components or JavaScript expressions between the opening and closing tags like this:
+
+```javascript
+<Parent><Child /></Parent>
+```
+
+`Parent` can read its children by accessing the special `this.props.children` prop.
+
+
+### Child Reconciliation
+
+**Reconciliation is the process by which React updates the DOM with each new render pass.** In general, children are reconciled according to the order in which they are rendered. For example, suppose two render passes generate the following respective markup:
+
+```html
+// Render Pass 1
+<Card>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</Card>
+// Render Pass 2
+<Card>
+  <p>Paragraph 2</p>
+</Card>
+```
+
+Intuitively, `<p>Paragraph 1</p>` was removed. Instead, React will reconcile the DOM by changing the text content of the first child and destroying the last child. React reconciles according to the *order* of the children.
+
+
+### Stateful Children
+
+For most components, this is not a big deal. However, for stateful components that maintain data in `this.state` across render passes, this can be very problematic.
+
+In most cases, this can be sidestepped by hiding elements instead of destroying them:
+
+```html
+// Render Pass 1
+<Card>
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</Card>
+// Render Pass 2
+<Card>
+  <p style={{'{{'}}display: 'none'}}>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</Card>
+```
+
+
+### Dynamic Children
+
+The situation gets more complicated when the children are shuffled around (as in search results) or if new components are added onto the front of the list (as in streams). In these cases where the identity and state of each child must be maintained across render passes, you can uniquely identify each child by assigning it a `key`:
+
+```javascript
+  render: function() {
+    var results = this.props.results;
+    return (
+      <ol>
+        {this.results.map(function(result) {
+          return <li key={result.id}>{result.text}</li>;
+        })}
+      </ol>
+    );
+  }
+```
+
+When React reconciles the keyed children, it will ensure that any child with `key` will be reordered (instead of clobbered) or destroyed (instead of reused).
+
+
+## Data Flow
+
+In React, data flows from owner to owned component through `props` as discussed above. This is effectively one-way data binding: owners bind their owned component's props to some value the owner has computed based on its `props` or `state`. Since this process happens recursively, data changes are automatically reflected everywhere they are used.
+
+
+## A Note on Performance
+
+You may be thinking that it's expensive to react to changing data if there are a large number of nodes under an owner. The good news is that JavaScript is fast and `render()` methods tend to be quite simple, so in most applications this is extremely fast. Additionally, the bottleneck is almost always the DOM mutation and not JS execution and React will optimize this for you using batching and change detection.
+
+However, sometimes you really want to have fine-grained control over your performance. In that case, simply override `shouldComponentUpdate()` to return false when you want React to skip processing of a subtree. See [the React reference docs](component-specs.html) for more information.
+
+> Note:
+>
+> If `shouldComponentUpdate()` returns false when data has actually changed, React can't keep your UI in sync. Be sure you know what you're doing while using it, and only use this function when you have a noticeable performance problem. Don't underestimate how fast JavaScript is relative to the DOM.

docs/docs/05-reusable-components.md

@@ -0,0 +1,143 @@
+---
+id: reusable-components
+title: Reusable Components
+layout: docs
+permalink: reusable-components.html
+prev: multiple-components.html
+next: forms.html
+---
+
+When designing interfaces, break down the common design elements (buttons, form fields, layout components, etc) into reusable components with well-defined interfaces. That way, the next time you need to build some UI you can write much less code, which means faster development time, less bugs, and less bytes down the wire.
+
+
+## Prop Validation
+
+As your app grows it's helpful to ensure that your components are used correctly. We do this by allowing you to specify `propTypes`. `React.PropTypes` exports a range of validators that can be used to make sure the data you receive is valid. When an invalid value is provided for a prop, an error will be thrown. Here is an example documenting the different validators provided:
+
+```javascript
+React.createClass({
+  propTypes: {
+    // You can declare that a prop is a specific JS primitive. By default, these
+    // are all optional.
+    optionalArray: React.PropTypes.array,
+    optionalBool: React.PropTypes.bool,
+    optionalFunc: React.PropTypes.func,
+    optionalNumber: React.PropTypes.number,
+    optionalObject: React.PropTypes.object,
+    optionalString: React.PropTypes.string,
+
+    // You can ensure that your prop is limited to specific values by treating
+    // it as an enum.
+    optionalEnum: React.PropTypes.oneOf(['News','Photos']),
+
+    // You can also declare that a prop is an instance of a class. This uses
+    // JS's instanceof operator.
+    someClass: React.PropTypes.instanceOf(SomeClass),
+
+    // You can chain any of the above with isRequired to make sure an error is
+    // thrown if the prop isn't provided.
+    requiredFunc: React.PropTypes.func.isRequired
+
+    // You can also specify a custom validator.
+    customProp: function(props, propName, componentName) {
+      if (!/matchme/.test(props[propName])) {
+        throw new Error('Validation failed!')
+      }
+    }
+  },
+  /* ... */
+});
+```
+
+
+## Default Prop Values
+
+React lets you define default values for your `props` in a very declarative way:
+
+```javascript
+var ComponentWithDefaultProps = React.createClass({
+  getDefaultProps: function() {
+    return {
+      value: 'default value'
+    };
+  }
+  /* ... */
+});
+```
+
+The result of `getDefaultProps()` will be cached and used to ensure that `this.props.value` will have a value if it was not specified by the parent component. This allows you to safely just use your props without having to write repetitive and fragile code to handle that yourself.
+
+
+## Transferring Props: A Shortcut
+
+A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. React provides `transferPropsTo()` to do just this.
+
+```javascript
+/** @jsx React.DOM */
+
+var CheckLink = React.createClass({
+  render: function() {
+    // transferPropsTo() will take any props passed to CheckLink
+    // and copy them to <a>
+    return this.transferPropsTo(<a>{'√ '}{this.props.children}</a>);
+  }
+});
+
+React.renderComponent(
+  <CheckLink href="javascript:alert('Hello, world!');">
+    Click here!
+  </CheckLink>,
+  document.getElementById('example')
+);
+```
+
+
+## Mixins
+
+Components are the best way to reuse code in React, but sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](http://en.wikipedia.org/wiki/Cross-cutting_concern). React provides `mixins` to solve this problem.
+
+One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](./working-with-the-browser.html) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
+
+```javascript
+/** @jsx React.DOM */
+
+var SetIntervalMixin = {
+  componentWillMount: function() {
+    this.intervals = [];
+  },
+  setInterval: function() {
+    this.intervals.push(setInterval.apply(null, arguments));
+  },
+  componentWillUnmount: function() {
+    this.intervals.map(clearInterval);
+  }
+};
+
+var TickTock = React.createClass({
+  mixins: [SetIntervalMixin], // Use the mixin
+  getInitialState: function() {
+    return {seconds: 0};
+  },
+  componentDidMount: function() {
+    this.setInterval(this.tick, 1000); // Call a method on the mixin
+  },
+  tick: function() {
+    this.setState({seconds: this.state.seconds + 1});
+  },
+  render: function() {
+    return (
+      <p>
+        React has been running for {this.state.seconds} seconds.
+      </p>
+    );
+  }
+});
+
+React.renderComponent(
+  <TickTock />,
+  document.getElementById('example')
+);
+```
+
+A nice feature of mixins is that if a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called.
+

docs/docs/06-forms.md

@@ -0,0 +1,132 @@
+---
+id: forms
+title: Forms
+layout: docs
+permalink: forms.html
+prev: reusable-components.html
+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.
+
+
+## Interactive Props
+
+Form components support a few props that are affected via user interactions:
+
+* `value`, supported by `<input>` and `<textarea>` components.
+* `checked`, supported by `<input>` components of type `checkbox` or `radio`.
+* `selected`, supported by `<option>` components.
+
+In HTML, the value of `<textarea>` is set via children. In React, you should use `value` instead.
+
+Form components allow listening for changes by setting a callback to the `onChange` prop. The `onChange` prop works across browsers to fire in response to user interactions when:
+
+* The `value` of `<input>` or `<textarea>` changes.
+* The `checked` state of `<input>` changes.
+* The `selected` state of `<option>` changes.
+
+Like all DOM events, the `onChange` prop is supported on all native components and can be used to listen to bubbled change events.
+
+
+## Controlled Components
+
+An `<input>` with `value` set is a *controlled* component. In a controlled `<input>`, the value of the rendered element will always reflect the `value` prop. For example:
+
+```javascript
+  render: function() {
+    return <input type="text" value="Hello!" />;
+  }
+```
+
+This will render an input that always has a value of `Hello!`. Any user input will have no effect on the rendered element because React has declared the value to be `Hello!`. If you wanted to update the value in response to user input, you could use the `onChange` event:
+
+```javascript
+  getInitialState: function() {
+    return {value: 'Hello!'};
+  },
+  handleChange: function(event) {
+    this.setState({value: event.target.value});
+  },
+  render: function() {
+    var value = this.state.value;
+    return <input type="text" value={value} onChange={this.handleChange} />;
+  }
+```
+
+In this example, we are simply accepting the newest value provided by the user and updating the `value` prop of the `<input>` component. This pattern makes it easy to implement interfaces that respond to or validate user interactions. For example:
+
+```javascript
+  handleChange: function(event) {
+    this.setState({value: event.target.value.substr(0, 140)});
+  }
+```
+
+This would accept user input but truncate the value to the first 140 characters.
+
+
+## Uncontrolled Components
+
+An `<input>` that does not supply a `value` (or sets it to `null`) is an *uncontrolled* component. In an uncontrolled `<input>`, the value of the rendered element will reflect the user's input. For example:
+
+```javascript
+  render: function() {
+    return <input type="text" />;
+  }
+```
+
+This will render an input that starts off with an empty value. Any user input will be immediately reflected by the rendered element. If you wanted to listen to updates to the value, you could use the `onChange` event just like you can with controlled components.
+
+If you want to initialize the component with a non-empty value, you can supply a `defaultValue` prop. For example:
+
+```javascript
+  render: function() {
+    return <input type="text" defaultValue="Hello!" />;
+  }
+```
+
+This example will function much like the **Controlled Components** example above.
+
+Likewise, `<input>` supports `defaultChecked` and `<option>` supports `defaultSelected`.
+
+
+## Advanced Topics
+
+
+### Why Controlled Components?
+
+Using form components such as `<input>` in React presents a challenge that is absent when writing traditional form HTML. For example, in HTML:
+
+```html
+  <input type="text" name="title" value="Untitled" />
+```
+
+This renders an input *initialized* with the value, `Untitled`. When the user updates the input, the node's value *property* will change. However, `node.getAttribute('value')` will still return the value used at initialization time, `Untitled`.
+
+Unlike HTML, React components must represent the state of the view at any point in time and not only at initialization time. For example, in React:
+
+```javascript
+  render: function() {
+    return <input type="text" name="title" value="Untitled" />;
+  }
+```
+
+Since this method describes the view at any point in time, the value of the text input should *always* be `Untitled`.
+
+
+### Why Textarea Value?
+
+In HTML, the value of `<textarea>` is usually set using its children:
+
+```html
+  <!-- counterexample: DO NOT DO THIS! -->
+  <textarea name="description">This is the description.</textarea>
+```
+
+For HTML, this easily allows developers to supply multiline values. However, since React is JavaScript, we do not have string limitations and can use `\n` if we want newlines. In a world where we have `value` and `defaultValue`, it is ambiguous what role children play. For this reason, you should not use children when setting `<textarea>` values:
+
+```javascript
+  <textarea name="description" value="This is a description." />
+```
+
+If you *do* decide to use children, they will behave like `defaultValue`.

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

@@ -0,0 +1,134 @@
+---
+id: working-with-the-browser
+title: Working With the Browser
+layout: docs
+permalink: working-with-the-browser.html
+prev: forms.html
+next: more-about-refs.html
+---
+
+React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library or existing code.
+
+
+## The Mock DOM
+
+React is so fast because it never talks to the DOM directly. React maintains a fast in-memory representation of the DOM. `render()` methods return a *description* of the DOM, and React can diff this description with the in-memory representation to compute the fastest way to update the browser.
+
+Additionally, React implements a full synthetic event system such that all event objects are guaranteed to conform to the W3C spec despite browser quirks, and everything bubbles consistently and in a performant way cross-browser. You can even use some HTML5 events in IE8!
+
+Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly.
+
+
+## Refs and getDOMNode()
+
+To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a `getDOMNode()` function which you can call to get a reference to it.
+
+> Note:
+>
+> `getDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `getDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
+
+In order to get a reference to a React component, you can either use `this` to get the current React component, or you can use refs to refer to a component you own. They work like this:
+
+```javascript
+/** @jsx React.DOM */
+
+var MyComponent = React.createClass({
+  handleClick: function() {
+    // Explicitly focus the text input using the raw DOM API.
+    this.refs.myTextInput.getDOMNode().focus();
+  },
+  render: function() {
+    // The ref attribute adds a reference to the component to
+    // this.refs when the component is mounted.
+    return (
+      <div>
+        <input type="text" ref="myTextInput" />
+        <input
+          type="button"
+          value="Focus the text input"
+          onClick={this.handleClick}
+        />
+      </div>
+    );
+  }
+});
+
+React.renderComponent(
+  <MyComponent />,
+  document.getElementById('example')
+);
+```
+
+
+## More About Refs
+
+To learn more about refs, including ways to use them effectively, see our [more about refs](./more-about-refs.html) documentation.
+
+
+## Component Lifecycle
+
+Components have three main parts of their lifecycle:
+
+* **Mounting:** A component is being inserted into the DOM.
+* **Updating:** A component is being re-rendered to determine if the DOM should be updated.
+* **Unmounting:** A component is being removed from the DOM.
+
+React provides lifecycle methods that you can specify to hook into this process. We provide **will** methods, which are called right before something happens, and **did** methods which are called right after something happens.
+
+
+### Mounting
+
+* `getInitialState(): object` is invoked before a component is mounted. Stateful components should implement this and return the initial state data.
+* `componentWillMount()` is invoked immediately before mounting occurs.
+* `componentDidMount(DOMElement rootNode)` is invoked immediately after mounting occurs. Initialization that requires DOM nodes should go here.
+
+
+### Updating
+
+* `componentWillReceiveProps(object nextProps)` is invoked when a mounted component receives new props. This method should be used to compare `this.props` and `nextProps` to perform state transitions using `this.setState()`.
+* `shouldComponentUpdate(object nextProps, object nextState): boolean` is invoked when a component decides whether any changes warrant an update to the DOM. Implement this as an optimization to compare `this.props` with `nextProps` and `this.state` with `nextState` and return false if React should skip updating.
+* `componentWillUpdate(object nextProps, object nextState)` is invoked immediately before updating occurs. You cannot call `this.setState()` here.
+* `componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)` is invoked immediately after updating occurs.
+
+
+### Unmounting
+
+* `componentWillUnmount()` is invoked immediately before a component is unmounted and destroyed. Cleanup should go here.
+
+
+### Mounted Methods
+
+_Mounted_ composite components also support the following methods:
+
+* `getDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node.
+* `forceUpdate()` can be invoked on any mounted component when you know that some deeper aspect of the component's state has changed without using `this.setState()`.
+
+> Note:
+>
+> The `DOMElement rootNode` argument of `componentDidMount()` and
+> `componentDidUpdate()` is a convenience. The same node can be obtained by
+> calling `this.getDOMNode()`.
+
+
+## Browser Support and Polyfills
+
+At Facebook, we support older browsers, including IE8. We've had polyfills in place for a long time to allow us to write forward-thinking JS. This means we don't have a bunch of hacks scattered throughout our codebase and we can still expect our code to "just work". For example, instead of seeing `+new Date()`, we can just write `Date.now()`. Since the open source React is the same as what we use internally, we've carried over this philosophy of using forward thinking JS.
+
+In addition to that philosophy, we've also taken the stance that we, as authors of a JS library, should not be shipping polyfills as a part of our library. If every library did this, there's a good chance you'd be sending down the same polyfill multiple times, which could be a sizable chunk of dead code. If your product needs to support older browsers, chances are you're already using something like [es5-shim](https://github.com/kriskowal/es5-shim).
+
+
+### Polyfills Needed to Support Older Browsers
+
+These six functions can be polyfilled using `es5-shim.js` from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim):
+
+* `Array.isArray`
+* `Array.prototype.forEach`
+* `Array.prototype.indexOf`
+* `Array.prototype.some`
+* `Date.now`
+* `Function.prototype.bind`
+
+Other required polyfills:
+
+* `Object.create` – Provided by `es5-sham.js` from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim).
+* `console.*` – Only needed when using the unminified build. If you need to polyfill this, try [paulmillr's console-polyfill](https://github.com/paulmillr/console-polyfill).

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

@@ -0,0 +1,135 @@
+---
+id: more-about-refs
+title: More About Refs
+layout: docs
+permalink: more-about-refs.html
+prev: working-with-the-browser.html
+next: tooling-integration.html
+---
+After returning the structure of your UI from the render method, you may find yourself wanting to "reach out" and invoke methods on component instances returned from render. Often, doing something like this isn't necessary for making data flow through your application, because the Reactive data flow always ensures that the most recent `props` are sent to each child that is output from `render()`. However there are a few cases, where it still might be necessary or beneficial.
+
+Consider the case when you wish to tell an `<input />` element (that exists within your instances sub-hierarchy) to focus after you update its value to be the empty string, `''`.
+
+```javascript
+  var App = React.createClass({
+    getInitialState: function() {
+      return {userInput: ''};
+    },
+    handleKeyUp: function(e) {
+      this.setState({userInput: e.target.value});
+    },
+    clearAndFocusInput: function() {
+      this.setState({userInput: ''}); // Clear the input
+      // We wish to focus the <input /> now!
+    },
+    render: function() {
+      return (
+        <div>
+          <div onClick={this.clearAndFocusInput}>
+            Click To Focus and Reset
+          </div>
+          <input
+            value={this.state.userInput}
+            onKeyUp={this.handleKeyUp}
+          />
+        </div>
+      );
+    }
+  });
+```
+
+
+Notice how, in this example, we want to "tell" the input something - something that it cannot infer from its props over time. In this case we want to "tell" it that it should now become focused. However, there are some challenges. What is returned from `render()` is not your actual composition of "child" components, it is merely a *description* of the children at a particular instance in time - a snapshot, if you will.
+
+> Note:
+>
+> Remember, what you return from `render()` is not your *actual* rendered children instances. What you return from `render()` is merely a *description* of the children instances in your component's sub-hierarchy at a particular moment in time.
+
+
+This means that you should never "hold onto" something that you return from `render()` and then expect it to be anything meaningful.
+
+```javascript
+  // counterexample: DO NOT DO THIS!
+  render: function() {
+    var myInput = <input />;          // I'm going to try to call methods on this
+    this.rememberThisInput = myInput; // input at some point in the future! YAY!
+    return (
+      <div>
+        <div>...</div>
+        {myInput}
+      </div>
+    );
+  }
+```
+
+In this counterexample, the `<input />` is merely a *description* of an `<input />`. This description is used to create a *real* **backing instance** for the `<input />`.
+
+So how do we talk to the *real* backing instance of the input?
+
+## The ref Attribute
+
+React supports a very special property that you can attach to any component that is output from `render()`. This special property allows you to refer to the corresponding **backing instance** of anything returned from `render()`. It is always guaranteed to be the proper instance, at any point in time.
+
+It's as simple as:
+
+**1.** Assign a `ref` attribute to anything returned from `render` such as:
+
+```html
+   <input ref="myInput" />
+```
+
+**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
+
+```javascript
+  this.refs.myInput
+```
+
+## Completing the Example
+
+```javascript
+  var App = React.createClass({
+    getInitialState: function() {
+      return {userInput: ''};
+    },
+    handleKeyUp: function(e) {
+      this.setState({userInput: e.target.value});
+    },
+    clearAndFocusInput: function() {
+      this.setState({userInput: ''}); // Clear the input
+      this.refs.theInput.getDOMNode().focus();   // Boom! Focused!
+    },
+    render: function() {
+      return (
+        <div>
+          <div onClick={this.clearAndFocusInput}>
+            Click To Focus and Reset
+          </div>
+          <input
+            ref="theInput"
+            value={this.state.userInput}
+            onKeyUp={this.handleKeyUp}
+          />
+        </div>
+      );
+    }
+  });
+```
+
+In this example, our render function returns a description of an `<input />` instance. But the true instance is accessed via `this.refs.theInput`. As long as a child component with `ref="theInput"` is returned from render, `this.refs.theInput` will access the proper instance. This even works on higher level (non-DOM) components such as `<Typeahead ref="myTypeahead" />`.
+
+
+## Summary
+
+Refs are a great way to send a message to a particular child instance in a way that would be inconvenient to do via streaming Reactive `props` and `state`. They should, however, not be your go-to abstraction for flowing data through your application. By default, use the Reactive data flow and save `ref`s for use cases that are inherently non-reactive.
+
+### Benefits:
+
+- You can define any public method on your component classes (such as a reset method on a Typeahead) and call those public methods through refs (such as `this.refs.myTypeahead.reset()`).
+- Performing DOM measurements almost always requires reaching out to a "native" component such as `<input />` and accessing its underlying DOM node via `this.refs.myInput.getDOMNode()`. Refs are one of the only practical ways of doing this reliably.
+- Refs are automatically book-kept for you! If that child is destroyed, its ref is also destroyed for you. No worrying about memory here (unless you do something crazy to retain a reference yourself).
+
+### Cautions:
+
+- *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.

docs/docs/08-tooling-integration.md

@@ -0,0 +1,52 @@
+---
+id: tooling-integration
+title: Tooling Integration
+layout: docs
+permalink: tooling-integration.html
+prev: more-about-refs.html
+next: addons.html
+---
+
+Every project uses a different system for building and deploying JavaScript. We've tried to make React as environment-agnostic as possible.
+
+## React
+
+### CDN-hosted React
+
+We provide CDN-hosted versions of React [on our download page](/react/downloads.html). These prebuilt files use the UMD module format. Dropping them in with a simple `<script>` tag will inject a `React` global into your environment. It should also work out-of-the-box in CommonJS and AMD environments.
+
+
+### Using master
+
+We have instructions for building from `master` [in our GitHub repository](https://github.com/facebook/react). We build a tree of CommonJS modules under `build/modules` which you can drop into any environment or packaging tool that supports CommonJS.
+
+## JSX
+
+### In-browser JSX Transform
+
+If you like using JSX, we provide an in-browser JSX transformer for development [on our download page](/react/downloads.html). Simply include a `<script type="text/jsx">` tag to engage the JSX transformer. Be sure to include the `/** @jsx React.DOM */` comment as well, otherwise the transformer will not run the transforms.
+
+> Note:
+>
+> The in-browser JSX transformer is fairly large and results in extraneous computation client-side that can be avoided. Do not use it in production — see the next section.
+
+
+### Productionizing: Precompiled JSX
+
+If you have [npm](http://npmjs.org/), you can simply run `npm install -g react-tools` to install our command-line `jsx` tool. This tool will translate files that use JSX syntax to plain JavaScript files that can run directly in the browser. It will also watch directories for you and automatically transform files when they are changed; for example: `jsx --watch src/ build/`. Run `jsx --help` for more information on how to use this tool.
+
+
+### Helpful Open-Source Projects
+
+The open-source community has built tools that integrate JSX with several build systems.
+
+* [reactify](https://github.com/andreypopp/reactify) - use JSX with [browserify](http://browserify.org/)
+* [grunt-react](https://github.com/ericclemmons/grunt-react) - [grunt](http://gruntjs.com/) task for JSX
+* [require-jsx](https://github.com/seiffert/require-jsx) - use JSX with [require.js](http://requirejs.org/)
+* [pyReact](https://github.com/facebook/react-python) - use JSX with [Python](http://www.python.org/)
+* [react-rails](https://github.com/facebook/react-rails) - use JSX with [Ruby on Rails](http://rubyonrails.org/)
+
+
+## React Page
+
+To get started on a new project, you can use [react-page](https://github.com/facebook/react-page/), a complete React project creator. It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload.

docs/docs/09-addons.md

@@ -0,0 +1,210 @@
+---
+id: addons
+title: Add-ons
+layout: docs
+permalink: addons.html
+prev: tooling-integration.html
+next: examples.html
+---
+
+`React.addons` is where we park some useful utilities for building React apps. **These should be considered experimental** but will eventually be rolled into core or a blessed utilities library.
+
+## CSS Animation and Transitions
+
+`ReactTransitions` is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. `ReactTransitions` is inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
+
+### Getting Started
+
+`ReactTransitionGroup` 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}
+/** @jsx React.DOM */
+
+var ReactTransitionGroup = React.addons.TransitionGroup;
+
+var TodoList = React.createClass({
+  getInitialState: function() {
+    return {items: ['hello', 'world', 'click', 'me']};
+  },
+  handleAdd: function() {
+    var newItems =
+      this.state.items.concat([prompt('Enter some text')]);
+    this.setState({items: newItems});
+  },
+  handleRemove: function(i) {
+    var newItems = this.state.items;
+    newItems.splice(i, 0)
+    this.setState({items: newItems});
+  },
+  render: function() {
+    var items = this.state.items.map(function(item, i) {
+      return (
+        <div key={i} onClick={this.handleRemove.bind(this, i)}>
+          {item}}
+        </div>
+      );
+    }.bind(this));
+    return (
+      <div>
+        <div><button onClick={this.handleAdd} /></div>
+        <ReactTransitionGroup transitionName="example">
+          {items}
+        </ReactTransitionGroup>
+      </div>
+    );
+  }
+});
+```
+
+In this component, when a new item is added `ReactTransitionGroup` it will get the `example-enter` CSS class and the `example-enter-active` CSS class added in the next tick. This is a convention based on the `transitionName` prop.
+
+You can use these classes to trigger a CSS animation or transition. For example, try adding this CSS and adding a new list item:
+
+```css
+.example-enter {
+  opacity: 0.01;
+  transition: opacity .5s ease-in;
+}
+
+.example-enter.example-enter-active {
+  opacity: 0.99;
+}
+```
+
+You'll notice that when you try to remove an item `ReactTransitionGroup` keeps it in the DOM. If you're using an unminified build of React you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS:
+
+```css
+.example-leave {
+  opacity: 0.99;
+  transition: opacity .5s ease-in;
+}
+
+.example-leave.example-leave-active {
+  opacity: 0.01;
+}
+```
+
+### Disabling Animations
+
+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 `ReactTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactTransitionGroup` to disable these animations.
+
+### Rendering a Different Component
+
+By default `ReactTransitionGroup` renders as a `span`. You can change this behavior by providing a `component` prop. For example, here's how you would render a `<ul>`:
+
+```javascript{3}
+<ReactTransitionGroup
+  transitionName="example"
+  component={React.DOM.ul}>
+  ...
+</ReactTransitionGroup>
+```
+
+`component` does not need to be a DOM component. It can be any component you want; even one you've written yourself!
+
+## ReactLink
+
+`ReactLink` is an easy way to express two-way binding with React.
+
+In React, data flows one way: from owner to child. This is because data only flows one direction in [the Von Neumann model of computing](http://en.wikipedia.org/wiki/Von_Neumann_architecture). You can think of it as "one-way data binding."
+
+However, there are lots of applications that require you to read some data and flow it back into your program. For example, when developing forms, you'll often want to update some React `state` when you receive user input. Or perhaps you want to perform layout in JavaScript and react to changes in some DOM element size.
+
+In React, you would implement this by listening to a "change" event, read from your data source (usually the DOM) and call `setState()` on one of your components. "Closing the data flow loop" explicitly leads to more understandable and easier-to-maintain programs. See [our forms documentation](./forms.html) for more information.
+
+Two-way binding -- implicitly enforcing that some value in the DOM is always consistent with some React `state` -- is concise and supports a wide variety of applications. We've provided `ReactLink`: syntactic sugar for setting up the common data flow loop pattern described above, or "linking" some data source to React `state`.
+
+> Note:
+>
+> ReactLink is just a thin wrapper and convention around the `onChange`/`setState()` pattern. It doesn't fundamentally change how data flows in your React application.
+
+### ReactLink: Before and After
+
+Here's a simple form example without using `ReactLink`:
+
+```javascript
+/** @jsx React.DOM */
+
+var NoLink = React.createClass({
+  getInitialState: function() {
+    return {value: 'Hello!'};
+  },
+  handleChange: function(event) {
+    this.setState({value: event.target.value});
+  },
+  render: function() {
+    var value = this.state.value;
+    return <input type="text" value={value} onChange={this.handleChange} />;
+  }
+});
+```
+
+This works really well and it's very clear how data is flowing, however with a lot of form fields it could get a bit verbose. Let's use `ReactLink` to save us some typing:
+
+```javascript{4,9}
+/** @jsx React.DOM */
+
+var WithLink = React.createClass({
+  mixins: [React.addons.LinkedStateMixin],
+  getInitialState: function() {
+    return {value: 'Hello!'};
+  },
+  render: function() {
+    return <input type="text" valueLink={this.linkState('value')} />;
+  }
+});
+```
+
+`LinkedStateMixin` adds a method ot your React component called `linkState()`. `linkState()` returns a `ReactLink` object which contains the current value of the React state and a callback to change it.
+
+`ReactLink` objects can be passed up and down the tree as props, so it's easy (and explicit) to set up two-way binding between a component deep in the hierarchy and state that lives higher in the hierarchy.
+
+### Under the Hood
+
+There are two sides to `ReactLink`: the place where you create the `ReactLink` instance and the place where you use it. To prove how simple `ReactLink` is, let's rewrite each side separately to be more explicit.
+
+#### ReactLink Without LinkedStateMixin
+
+```javascript{7-9,11-14}
+/** @jsx React.DOM */
+
+var WithoutMixin = React.createClass({
+  getInitialState: function() {
+    return {value: 'Hello!'};
+  },
+  handleChange: function(newValue) {
+    this.setState({value: newValue});
+  },
+  render: function() {
+    var valueLink = {
+      value: this.state.value,
+      requestChange: this.handleChange
+    };
+    return <input type="text" valueLink={valueLink} />;
+  }
+});
+```
+
+As you can see, `ReactLink` objects are very simple objects that just have a `value` and `requestChange` prop. And `LinkedStateMixin` is similarly simple: it just populates those fields with a value from `this.state` and a callback that calls `this.setState()`.
+
+#### ReactLink Without valueLink
+
+```javascript
+/** @jsx React.DOM */
+
+var WithoutLink = React.createClass({
+  mixins: [React.addons.LinkedStateMixin],
+  getInitialState: function() {
+    return {value: 'Hello!'};
+  },
+  render: function() {
+    var valueLink = this.linkState('value');
+    var handleChange = function(e) {
+      valueLink.requestChange(e.target.value);
+    };
+    return <input type="text" value={valueLink.value} onChange={handleChange} />;
+  }
+});
+```
+
+The `valueLink` prop is also quite simple. It simply handles the `onChange` event and calls `this.props.valueLink.requestChange()` and also uses `this.props.valueLink.value` instead of `this.props.value`. That's it!

docs/docs/10-examples.md

@@ -0,0 +1,22 @@
+---
+id: examples
+title: Examples
+layout: docs
+permalink: examples.html
+prev: addons.html
+---
+
+### Production Apps
+
+* All of [Instagram.com](http://instagram.com/) is built on React.
+* Many components on [Facebook.com](http://www.facebook.com/), including the commenting interface, ads creation flows, and page insights.
+* [Khan Academy](http://khanacademy.org/) is using React for most new JS development.
+
+
+### Sample Code
+
+* We've included [a step-by-step comment box tutorial](./tutorial.html).
+* [The React starter kit](/react/downloads.html) includes several examples which you can [view online in our GitHub repository](https://github.com/facebook/react/tree/master/examples/).
+* [React Page](https://github.com/facebook/react-page) is a simple React project creator to get you up-and-running quickly with React. It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload.
+* [React one-hour email](https://github.com/petehunt/react-one-hour-email/commits/master) goes step-by-step from a static HTML mock to an interactive email reader (written in just one hour!)
+* [Rendr + React app template](https://github.com/petehunt/rendr-react-template/) demonstrates how to use React's server rendering capabilities.

docs/docs/OUTLINE.md

@@ -0,0 +1,96 @@
+---
+id: OUTLINE
+title: Goals of the documentation
+layout: docs
+prev: 09.1-tutorial.html
+---
+- Flow of docs should mimic progression of questions a new user would ask
+- High information density -- assume the reader is adept at JS
+- Talk about best practices
+- JSFiddles for all code samples
+- Provide background for some of the design decisions
+- Less words less words less words!
+
+## Outline
+
+Motivation / Why React?
+- Declarative (simple)
+- Components (separation of concerns)
+- Give it 5 minutes
+
+Displaying data
+- Hello world example
+- Reactive updates
+- Components are just functions
+- JSX syntax (link to separate doc?)
+- JSX gotchas
+
+Interactivity and dynamic UIs
+- Click handler example
+- Event handlers / synthetic events (link to w3c docs)
+- Under the hood: autoBind and event delegation (IE8 notes)
+- React is a state machine
+- How state works
+- What components should have state?
+- What should go in state?
+- What shouldn't go in state?
+
+Scaling up: using multiple components
+- Motivation: separate concerns
+- Composition example
+- Ownership (and owner vs. parent)
+- Children
+- Data flow (one-way data binding)
+- A note on performance
+
+Building effective reusable components
+- You should build a reusable component library (CSS, testing etc)
+- Prop validation
+- Transferring props: a shortcut
+- Mixins
+- Testing
+
+Forms
+
+Working with the browser
+- The mock DOM
+- Refs / getDOMNode()
+- More about refs
+- Component lifecycle
+- Browser support and polyfills
+
+Working with your environment
+- CDN-hosted React
+- Using master
+- In-browser JSX transform
+- Productionizing: precompiled JSX
+- Helpful open-source projects
+
+Integrating with other UI libraries
+- Using jQuery plugins
+- Letting jQuery manage React components
+- Using with Backbone.View
+- CoffeeScript
+- Moving from Handlebars to React: an example
+
+Server / static rendering
+- Motivation
+- Simple example
+- How does it work? (No DOM)
+- Rendr + React
+
+Big ideas
+- Animation
+- Bootstrap bindings (responsive grids)
+- Reactive CSS
+- Web workers
+- Native views
+
+Case studies
+- Comment box tutorial from scratch
+- From HTML mock to application: React one-hour email
+- Jordan's LikeToggler example
+
+Reference
+- API
+- DOM differences

docs/docs/advanced-components.md

@@ -1,119 +0,0 @@
----
-id: docs-advanced-components
-title: Advanced Components
-description: How to build advanced composite components.
-layout: docs
-prev: event-handling.html
-next: mixins.html
----
-
-Composite components extend a `ReactCompositeComponent` base class that provides
-a very powerful API that makes React flexible and able to easily work with other
-libraries and frameworks.
-
-## Lifecycle Methods
-
-Composite components can optionally implement lifecycle methods that are invoked
-at various stages in the [component lifecycle](component-lifecycle.html) that
-each have unique guarantees.
-
-### Mounting
-
- - `getInitialState(): object` is invoked before a component is mounted.
-   Stateful components should implement this and return the initial state data.
- - `componentWillMount()` is invoked immediately before mounting occurs.
- - `componentDidMount(DOMElement rootNode)` is invoked immediately after
-   mounting occurs. Initialization that requires DOM nodes should go here.
-
-### Updating
-
- - `componentWillReceiveProps(object nextProps)` is invoked when a mounted
-   component receives new props. This method should be used to compare
-   `this.props` and `nextProps` to perform state transitions using
-   `this.setState()`.
- - `shouldComponentUpdate(object nextProps, object nextState): boolean` is
-   invoked when a component decides whether any changes warrant an update to the
-   DOM. Implement this as an optimization to compare `this.props` with
-   `nextProps` and `this.state` with `nextState` and return false if React
-   should skip updating.
- - `componentWillUpdate(object nextProps, object nextState)` is invoked
-   immediately before updating occurs. You cannot call `this.setState()` here.
- - `componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)`
-   is invoked immediately after updating occurs.
-
-### Unmounting
-
- - `componentWillUnmount()` is invoked immediately before a component is
-   unmounted and destroyed. Cleanup should go here.
-
-## Mounted Methods
-
-_Mounted_ composite components also support the following methods:
-
- - `getDOMNode(): DOMElement` can be invoked on any mounted component in order
-   to obtain a reference to its rendered DOM node.
- - `forceUpdate()` can be invoked on any mounted component when you know that
-   some deeper aspect of the component's state has changed without using
-   `this.setState()`.
-
-> Note:
->
-> The `DOMElement rootNode` argument of `componentDidMount()` and
-> `componentDidUpdate()` is a convenience. The same node can be obtained by
-> calling `this.getDOMNode()`.
-
-## Component Refs
-
-A common use case of event callbacks or the lifecycle methods is to operate on a
-component returned by `render()`. For example, consider a search component that
-should auto-focus the input once mounted:
-
-```javascript
-var SearchForm = React.createClass({
-  render: function() {
-    return (
-      <form action={this.props.action}>
-        <input type="search" placeholder="Search..." />
-      </form>
-    );
-  },
-  componentDidMount: function(rootNode) {
-    var searchInput = rootNode.firstChild;
-    searchInput.focus();
-  }
-});
-```
-
-Although this implementation works, it is fragile because `componentDidMount()`
-now relies on `render()` returning a particular DOM structure.
-
-React provides a better way for composite components to reference components
-that it constructs in its `render()` method through the use of refs. A component
-can assign a `ref` to any component it constructs. This will create a reference
-to those components on `this.refs`. For example:
-
-```javascript{5,10}
-var SearchForm = React.createClass({
-  render: function() {
-    return (
-      <form action={this.props.action}>
-        <input type="search" placeholder="Search..." ref="searchInput" />
-      </form>
-    );
-  },
-  componentDidMount: function(rootNode) {
-    var searchInput = this.refs.searchInput.getDOMNode();
-    searchInput.focus();
-  }
-});
-```
-
-In this example, `this.refs.searchInput` will reference the `<input>` component
-and is available in most lifecycle methods and event callbacks. We obtain a
-reference to the `<input>`'s DOM node using `getDOMNode()`.
-
-> Note:
->
-> If you want to preserve compatibility with Google Closure Compiler's
-> property crushing in `ADVANCED_OPTIMIZATIONS` mode, make sure to use string
-> literals with `this.refs`.

docs/docs/api.md

@@ -1,150 +0,0 @@
----
-id: docs-api
-title: React API
-layout: docs
-prev: mixins.html
----
-
-## React
-
-`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.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.autoBind
-
-```javascript
-function autoBind(function method)
-```
-
-Marks the provided function to be automatically bound to each React component instance created. This allows React components to define automatically bound methods and ensure that when called they will always reference their current instance.
-
-Example:
-
-```javascript
-React.createClass({
-  click: React.autoBind(function(evt) {
-    this.setState({jumping: true});
-  }),
-  render: function() {
-    // Look: no bind!
-    return <a onClick={this.click}>Jump</a>;
-  }
-});
-```
-
-#### React.createClass
-
-```javascript
-function createClass(object specification)
-```
-
-Creates a component given a specification. A component implements a `render` method which returns a single child. That child may have an arbitrarily deep child structure. One thing that makes components different than a standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you.
-
-#### React.renderComponent
-
-```javascript
-ReactComponent renderComponent(ReactComponent container, DOMElement mountPoint)
-```
-
-Renders a React component into the DOM in the supplied `container`.
-
-If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
-
-## AbstractEvent
-
-Your event handlers will be passed instances of `AbstractEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event (such as `stopPropagation()` and `preventDefault()`) except they work exactly the same across all browsers.
-
-If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it.
-
-## ReactComponent
-
-Component classses created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming `ReactComponent`s.
-
-#### 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 that are not in nextProps.
-
-#### 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. This is usually used to pass down properties to the returned root component. `targetComponent`, now updated with some new props is returned as a convenience.
-
-#### setState
-
-```javascript
-setState(object nextState)
-```
-
-Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.
-
-**Note:** *NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
-
-**Note:** `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
-
-#### replaceState
-
-```javascript
-replaceState(object nextState)
-```
-
-Like `setState()` but deletes any pre-existing state keys that are not in nextState.
-
-#### forceUpdate()
-
-```javascript
-forceUpdate()
-```
-
-If your `render()` method reads from something other than `this.props` or `this.state` you'll need to tell React when it needs to re-run `render()`. Use `forceUpdate()` to cause React to automatically re-render. This will cause `render()` to be called on the component and all of its children but React will only update the DOM if the markup changes.
-
-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.
-
-```javascript
-object getInitialState()
-componentWillMount()
-componentDidMount(DOMElement domNode)
-componentWillReceiveProps(object nextProps)
-boolean shouldComponentUpdate(object nextProps, object nextState)
-componentWillUpdate(object nextProps, object nextState)
-ReactComponent render()
-componentDidUpdate(object prevProps, object prevState, DOMElement domNode)
-componentWillUnmount()
-```
-
-See the [advanced components](advanced-components.html) documentation for more details on these lifecycle methods.

docs/docs/common-questions.md

@@ -1,28 +0,0 @@
----
-id: docs-common-questions
-title: Common Questions
-layout: docs
-prev: tutorial.html
-next: syntax.html
----
-
-### What browsers does React support?
-
-React supports the latest two Chrome, Firefox, Safari, and Internet Explorer versions. React can work with Internet Explorer 8 with polyfills.
-
-### How do I get React to support Internet Explorer 8?
-
-React requires ES5 JavaScript shims to run in Internet Explorer 8. Include the [ES5 Shims](https://github.com/kriskowal/es5-shim) to implement these shims.
-
-### Who uses React?
-
-The [Instagram](http://instagram.com/) website is built entirely in React. The [Facebook](https://www.facebook.com/) website is also increasingly using React, including the common commenting plugin across the site.
-
-### I don't get it. React is confusing!
-
-[This blog post by a member of the React team](http://www.quora.com/Pete-Hunt/Posts/React-Under-the-Hood) talks about some of the reasons
-why React is designed the way that it is.
-
-### Can I integrate with other JavaScript libraries?
-
-Absolutely! In fact, we encourage it! See [our GitHub repo](http://github.com/facebook/react/) for a [TodoMVC example using Backbone](https://github.com/facebook/react/tree/master/examples/todomvc-backbone) and a [jQuery + Bootstrap modal demo](https://github.com/facebook/react/tree/master/examples/jquery-bootstrap).

docs/docs/component-basics.md

@@ -1,73 +0,0 @@
----
-id: docs-component-basics
-title: Component Basics
-description: What are components?
-layout: docs
-next: component-data.html
-prev: syntax.html
----
-
-_Components_ are the basic units of composition in React. Components encapsulate
-the logic necessary to take input parameters and render markup. Components can
-be rendered into an existing DOM element on the page by using
-`React.renderComponent`:
-
-```javascript
-// Replaces everything in `document.body` with <div>Hello, world!</div>;
-React.renderComponent(<div>Hello, world!</div>, document.body);
-```
-
-Keep in mind that `<div>` is **not** a DOM element! Keep reading...
-
-## Types of Components
-
-There are two types of components:
-
- - **Composite Components**
- - **DOM Components**
-
-### Composite Components <small>such as `TodoApp` and `Typeahead`.</small>
-
-The majority of your React code will be implementing composite components.
-
-Composite components are higher-level components with custom rendering logic
-that may compose other composite components or DOM components.
-
-```javascript
-/** @jsx React.DOM */
-var LinkButton = React.createClass({
-  render: function() {
-    return <a className="btn" />;
-  }
-});
-
-var myButton = <LinkButton />;
-```
-
-This example defines a `LinkButton` component class using `React.createClass()`,
-and its `render()` method composes the `<a>` DOM component.
-
-### DOM Components <small>such as `div` and `span`.</small>
-
-DOM components are the set of classes that correspond to browser DOM elements.
-They are defined in `React.DOM` and can be brought "into scope" by setting
-`@jsx React.DOM` in the docblock. See [JSX Syntax](syntax.html) for more
-details.
-
-Although `React.DOM` components look like browser DOM elements, they differ in a
-few ways:
-
-- All property names, including event handlers, are camelCased.
-- JavaScript identifiers should be used, namely `className` and `htmlFor`.
-- The `style` prop expects an object instead of a string. The object should map
-  camelCased style properties to values, e.g. `{backgroundColor: '#fff'}`.
-
-Here is an example of a React link styled as a button with a click handler:
-
-```javascript
-/** @jsx React.DOM */
-var handleClick = function() {alert('Clicked!');};
-var inlineStyle = {textDecoration: 'none'};
-
-var myLink = <a className="btn" onClick={handleClick} style={inlineStyle} />;
-```

docs/docs/component-data.md

@@ -1,145 +0,0 @@
----
-id: docs-component-data
-title: Component Data
-description: How is data passed into a component?
-layout: docs
-prev: component-basics.html
-next: component-lifecycle.html
----
-
-## Props
-
-Components use data to determine what should be rendered. For example:
-
-```javascript
-var LikeLink = React.createClass({
-  render: function() {
-    var text = this.props.liked ? 'Liked' : 'Like';
-    return <a>{text}</a>;
-  }
-});
-var myLikeLink = <LikeLink liked={false} />;
-```
-
-In this example, `LikeLink` takes `liked` as boolean data. This type of data
-that is passed in is called a "prop". Examples of props on DOM components
-include `className` and `onClick`.
-
-Whenever a component's props change, its `render()` function will be
-re-evaluated and the DOM will be updated. React will ensure that the DOM is
-always kept up-to-date.
-
-## State
-
-Let's build a small `LikeApp` application that makes use of the `<LikeLink>`
-component from above. It should start off unliked and we should be able to like
-it by clicking the link:
-
-```javascript
-var LikeApp = React.createClass({
-  render: function() {
-    var isClicked = false;
-    return <LikeLink liked={isClicked} onClick={this.handleClick.bind(this)} />;
-  },
-  handleClick: function() {
-    // Somehow update `isClicked`.
-  }
-});
-```
-
-This renders a `<LikeLink>` with a click listener. However, it is not clear how
-`handleClick` should update `isClicked` to true. `LikeApp` needs a way to store
-**state** about whether or not it has been clicked.
-
-### State vs. Props
-
-State is data that is managed _internally_ by a composite component. Like props,
-the `render()` function will be re-evaluated whenever state changes. Props and
-state differ in that:
-
- - Props are passed in from the creator.
- - State is private to and managed by the component.
-
-### Managing State
-
-Let's update our `LikeApp` component using state:
-
-```javascript{2-4,6,10}
-var LikeApp = React.createClass({
-  getInitialState: function() {
-    return {isClicked: false};
-  },
-  render: function() {
-    var isClicked = this.state.isClicked;
-    return <LikeLink liked={isClicked} onClick={this.handleClick.bind(this)} />;
-  },
-  handleClick: function() {
-    this.setState({isClicked: true});
-  }
-});
-```
-
-There's a lot going on here, so let's work our way from top to bottom:
-
- - `getInitialState()` describes what state data looks like when the component
-   is created.
- - In `render()`, state data can be accessed via `this.state`.
- - When the link is clicked, we update state using `setState()`.
-
-Now when we click the link, the `<LikeLink>` will get updated, right? Wrong.
-
-## Transferring Props
-
-If you have been following carefully, you may have noticed that although we pass
-a click handler into `<LikeLink>` as a prop, `LikeLink` does not do anything
-with `this.props.onClick`! Let's fix that.
-
-```javascript{4}
-var LikeLink = React.createClass({
-  render: function() {
-    var text = this.props.liked ? 'Liked' : 'Like';
-    return <a onClick={this.props.onClick}>{text}</a>;
-  }
-});
-```
-
-Although this works, realize that this would quickly become tedious if we wanted
-to also transfer `href`, `title`, `target`, and other events from `this` to the
-rendered `<a>`. React provides a convenience method, `transferPropsTo()`, for
-transferring props:
-
-```javascript{4}
-var LikeLink = React.createClass({
-  render: function() {
-    var text = this.props.liked ? 'Liked' : 'Like';
-    return this.transferPropsTo(<a>{text}</a>);
-  }
-});
-```
-
-This will transfer all props from `this` to the specified component (including
-`onClick`).
-
-## Summary
-
-Now we are done. `LikeApp` renders an unliked link which, when clicked, will:
-
-1. Update the internal state of `LikeApp`.
-2. Change the props passed into `LikeLink`.
-3. Change the return value of `render()`.
-4. Trigger an update to the DOM.
-
-It's worth noting that React will handle new return values of `render()` by
-making the minimal set of mutations necessary to bring the DOM up-to-date. In
-this case, only the `textContent` of the rendered link will be mutated.
-
-In summary:
-
- - Props are passed in whereas state is managed internally by a component.
- - Never mutate `this.props` or `this.state`. You should pass props into other
-   components and mutate state using `setState()`.
- - State is private. Never read `state` or call `setState()` on
-   anything but `this`.
- - Whenever props or state changes, `render()` will be re-evaluated and the DOM
-   updated. Also, `render()` should not depend on anything besides `this.props`
-   and `this.state`.

docs/docs/component-lifecycle.md

@@ -1,85 +0,0 @@
----
-id: docs-component-lifecycle
-title: Component Lifecycle
-description: What happens when I render a React component?
-layout: docs
-prev: component-data.html
-next: event-handling.html
----
-
-## Mounting
-
-[We have previously seen](component-basics.html) how to render components into
-existing DOM elements on the page:
-
-```javascript
-React.renderComponent(<div>Hello, world!</div>, document.body);
-```
-
-In this one simple line, we have accomplished the following:
-
- - A `<div>` (defined by `React.DOM.div`) component is instantiated.
- - The component is **mounted** into `document.body`.
-
-**Mounting** is the process of initializing a React component by creating its
-DOM nodes and inserting the them into a supplied container node.
-
-At this point, the entire page consists of a single `<div>` with "Hello,
-world!".
-
-## Updating
-
-Let's add a second call to `React.renderComponent()` after three
-seconds:
-
-```javascript{2-4}
-React.renderComponent(<div>Hello, world!</div>, document.body);
-setTimeout(function() {
-  React.renderComponent(<div>Goodbye, world.</div>, document.body);
-}, 3000);
-```
-
-The second call to `React.renderComponent()` will trigger the following:
-
- - The `<div>` component will check the new props to see if anything changed.
- - The set of changes are used to **update** the DOM node as necessary.
-
-**Updating** is the process of mutating the rendered DOM nodes and occurs
-whenever either props or state has changed. This ensures that the rendered DOM
-is consistent with the data.
-
-## Unmounting
-
-Let's add one final call to `React.renderComponent()` after another three
-seconds:
-
-```javascript{5-7}
-React.renderComponent(<div>Hello, world!</div>, document.body);
-setTimeout(function() {
-  React.renderComponent(<div>Goodbye, world.</div>, document.body);
-}, 3000);
-setTimeout(function() {
-  React.renderComponent(<img src="/images/fin.png" />, document.body);
-}, 6000);
-```
-
-The third call to `React.renderComponent()` will trigger the following:
-
- - An `<img>` (defined by `React.DOM.img`) component is instantiated.
- - React will compare the `<div>` component with the `<img>` component.
- - Since the component class is different, the `<div>` component will be
-   **unmounted**.
- - The `<img>` component will then be mounted into `document.body`.
-
-**Unmounting** is the process of releasing resources that have been allocated by
-a component. This allows user interfaces built with React to live long without
-memory leaks.
-
-Components can also be unmounted using
-`React.unmountAndReleaseReactRootNode()`:
-
-```javascript
-React.unmountAndReleaseReactRootNode(document.body);
-```
-
-This will unmount any components mounted immediately within `document.body`.

docs/docs/event-handling.md

@@ -1,224 +0,0 @@
----
-id: docs-event-handling
-title: Event Handling
-description: How do events work with React components?
-layout: docs
-prev: component-lifecycle.html
-next: advanced-components.html
----
-
-Events in React work the way they do with HTML, except the event names are
-camelCased.
-
-```javascript
-var Clicker = React.createClass({
-  render: function() {
-    return <span onClick={this.handleClick}>Click me!</span>;
-  },
-  handleClick: function(event) {
-    alert('You clicked me!');
-  }
-});
-```
-
-When `<Clicker>` is clicked, the `handleClick()` function will get fired. Under
-the hood, React uses top-level event delegation to achieve high performance.
-
-## Automatically Binding Callbacks
-
-Just like any callback in JavaScript, if you want to refer to the component as
-`this` from the callback, you need to bind the callback to the component:
-
-```javascript{3}
-var Clicker = React.createClass({
-  render: function() {
-    var handleClick = this.handleClick.bind(this);
-    return <span onClick={handleClick}>Click me!</span>;
-  },
-  handleClick: function(event) {
-    alert(this.ALERT_MESSAGE);
-  },
-  ALERT_MESSAGE: 'You clicked me!'
-});
-```
-
-React provides a convenient and _efficient_ way to bind methods using
-`React.autoBind()`:
-
-```javascript{3,5-7}
-var Clicker = React.createClass({
-  render: function() {
-    return <span onClick={this.handleClick}>Click me!</span>;
-  },
-  handleClick: React.autoBind(function(event) {
-    alert(this.ALERT_MESSAGE);
-  }),
-  ALERT_MESSAGE: 'You clicked me!'
-});
-```
-
-> Note:
->
-> Binding a function allocates memory to create a new bound function. Since
-> `render()` may be invoked many times, it is a bad place to bind functions.
-> `React.autoBind()` sidesteps this issue by only binding once at instantiation
-> time.
-
-## DOM Events
-
-React uses [top-level event delegation](http://davidwalsh.name/event-delegate)
-to achieve high performance when implementing DOM events. For each type of DOM
-event, React adds a single top-level listener and determines which event
-handlers to execute by simulating event capturing and bubbling.
-
-DOM event handlers are called with a normalized `AbstractEvent` object that has
-cross-browser compatible implementations of `stopPropagation` and
-`preventDefault()`. If you need access to the raw browser event, you can use the
-`nativeEvent` property.
-
-> Note:
->
-> The `AbstractEvent` object is JSON serializable so that React applications can
-> be executed inside web workers.
-
-### Touch Events
-
-If you want to use touch events, you must configure React's event system to
-initialize them:
-
-```javascript
-// Invoke before calling `React.renderComponent()`.
-React.initializeTouchEvents(true);
-```
-
-## Custom Events
-
-Notice that event listeners are attached by simply passing them into components
-as props. For DOM components, events are handled using top-level event
-delegation. For composite components, event handling is up to the component's
-implementation.
-
-Here is an example of a toggle link that fires a custom `onToggle` event:
-
-```javascript
-var ToggleLink = React.createClass({
-  getInitialState: function() {
-    return {isEnabled: false};
-  },
-  render: function() {
-    return <a onClick={this.handleClick}>Toggle</a>;
-  },
-  handleClick: React.autoBind(function() {
-    var willEnable = !this.state.isEnabled;
-    if (this.props.onToggle) {
-      this.props.onToggle(willEnable)
-    }
-    this.setState({isEnabled: willEnable});
-  })
-});
-
-var handleToggle = function(enabled) {
-  alert(enabled ? 'Enabled.' : 'Disabled.');
-};
-var myToggleLink = <ToggleLink onToggle={handleToggle} />;
-```
-
-### Common Patterns
-
-With React your event handlers should be quite small. Large event handlers may
-be symptomatic of code that should be moved into helpers or into `render()`.
-Here are some common usage patterns for event handlers.
-
-#### Updating State
-
-The most common thing to do in response to a user action is to call
-`this.setState()` to update the component's state, which will in turn trigger
-an update to the rendered component.
-
-#### Server Requests
-
-Many event handlers will issue a server request to read or write some data in
-response to an event. The response handler for the request will often call
-`this.setState()`.
-
-#### Invoke a Callback
-
-Your component will often be a small, reusable building block that does not know
-how to respond to a user action. In these situations, we delegate the
-responsibility to the owner by exposing a handler on `this.props`. This is what
-the `ToggleLink` example above is doing.
-
-#### Inter-component Communication
-
-A common scenario involves communicating to **Component A** that a user action
-has occurred on **Component B**. To solve this problem, a common parent to
-both components should listen for the event on **Component B**, update its
-internal state, and pass that data into **Component A**.
-
-For example, say we have two components: **Clicker**, a component that fires an
-`onCountChange` custom event, and **ClickCountLabel**, a component that displays
-the number of clicks that have happened:
-
-```javascript
-var Clicker = React.createClass({
-  getInitialState: function() {
-    return {count: 0};
-  },
-  render: function() {
-    return <span onClick={this.handleClick}>Click me!</span>;
-  },
-  handleClick: React.autoBind(function() {
-    this.setState({count: this.state.count + 1});
-    if (this.props.onCountChange) {
-      this.props.onCountChange(this.state.count);
-    }
-  })
-});
-
-var ClickCountLabel = React.createClass({
-  render: function() {
-    return <p>You have clicked <strong>{this.props.count}</strong> times.</p>;
-  }
-});
-
-var ClickApp = React.createClass({
-  render: function() {
-    var count = 0;
-    return (
-      <div>
-        <Clicker onCountChange={this.handleCountChange} />
-        <ClickCountLabel count={count} />
-      </div>
-    );
-  },
-  handleCountChange: React.autoBind(function(count) {
-    // Somehow update `count`.
-  })
-});
-```
-
-In order to communicate the click count from `Clicker` to `ClickCountLabel`, we
-modify `ClickApp` to maintain state that will be passed into `ClickCountLabel`:
-
-```javascript{2-4,6,15}
-var ClickApp = React.createClass({
-  getInitialState: function() {
-    return {count: 0};
-  },
-  render: function() {
-    var count = this.state.count;
-    return (
-      <div>
-        <Clicker onCountChange={this.handleCountChange} />
-        <ClickCountLabel count={count} />
-      </div>
-    );
-  },
-  handleCountChange: React.autoBind(function(count) {
-    this.setState({count: count});
-  })
-});
-```
-
-Now when `Clicker` fires the `onCountChange` event, the `ClickCountLabel` will
-get updated!

docs/docs/getting-started.md

@@ -1,5 +1,5 @@
 ---
-id: docs-getting-started
+id: getting-started
 title: Getting Started
 layout: docs
 next: tutorial.html
@@ -44,7 +44,7 @@ In the root directory of the starter kit, create a `helloworld.html` with the fo
 </html>
 ```
 
-The XML syntax inside of JavaScript is called JSX; check out the [JSX syntax](syntax.html) to learn more about it. In order to translate it to vanilla JavaScript we use `<script type="text/jsx">` and include `JSXTransformer.js` to actually perform the transformation in the browser.
+The XML syntax inside of JavaScript is called JSX; check out the [JSX syntax](jsx-in-depth.html) to learn more about it. In order to translate it to vanilla JavaScript we use `<script type="text/jsx">` and include `JSXTransformer.js` to actually perform the transformation in the browser.
 
 ### Separate File
 
@@ -84,10 +84,14 @@ The file `build/helloworld.js` is autogenerated whenever you make a change.
 /** @jsx React.DOM */
 React.renderComponent(
   React.DOM.h1(null, 'Hello, world!'),
-  document.getElementyById('example')
+  document.getElementById('example')
 );
 ```
 
+> Note:
+>
+> The comment parser is very strict right now, in order for it to pick up the `@jsx` modifier, two conditions are required. The `@jsx` comment block must be the first comment on the file. The comment must start with `/**` (`/*` and `//` will not work). If the parser can't find the `@jsx` comment, it will output the file without transforming it.
+
 Update your HTML file as below:
 
 ```html{6,10}

docs/docs/index.html

@@ -0,0 +1,4 @@
+---
+layout: redirect
+destination: getting-started.html
+---

docs/docs/mixins.md

@@ -1,65 +0,0 @@
----
-id: docs-mixins
-title: Mixins
-layout: docs
-prev: advanced-components.html
-next: api.html
----
-
-Mixins allow code to be shared between multiple React components. They are pretty similar to mixins
-in Python or traits in PHP. Let's look at a simple example:
-
-```javascript
-var MyMixin = {
-  getMessage: function() {
-    return 'hello world';
-  }
-};
-
-var MyComponent = React.createClass({
-  mixins: [MyMixin],
-  render: function() {
-    return <div>{this.getMessage()}</div>;
-  }
-});
-```
-
-A class can use multiple mixins, but no two mixins can define the same method. Two mixins can, however,
-implement the same [lifecycle method](component-lifecycle.html). In this case, each implementation will be invoked one after another.
-
-The only exception is the `shouldComponentUpdate` lifecycle method. This method may only be implemented once
-(either by a mixin or by the component).
-
-```javascript
-var Mixin1 = {
-  componentDidMount: function() {
-    console.log('Mixin1.componentDidMount()');
-  }
-};
-
-var Mixin2 = {
-  componentDidMount: function() {
-    console.log('Mixin2.componentDidMount()');
-  }
-};
-
-
-var MyComponent = React.createClass({
-  mixins: [Mixin1, Mixin2],
-  render: function() {
-    return <div>hello world</div>;
-  }
-});
-```
-
-When `MyComponent` is mounted into the page, the following text will print to the console:
-
-```
-Mixin1.componentDidMount()
-Mixin2.componentDidMount()
-```
-
-## When should you use mixins?
-
-In general, add a mixin whenever you want a component to share some utility methods, public interface,
-or lifecycle behavior. Often it's appropriate to use them as you would use a superclass in another OOP language.

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

@@ -0,0 +1,73 @@
+---
+id: top-level-api
+title: Top-Level API
+layout: docs
+permalink: top-level-api.html
+next: component-api.html
+---
+
+## React
+
+`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.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
+function createClass(object specification)
+```
+
+Creates a component given a specification. A component implements a `render` method which returns **one single** child. That child may have an arbitrarily deep child structure. One thing that makes components different than standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you.
+
+For more information about the specification object, see [Component Specs and Lifecycle](component-specs.html).
+
+
+### React.renderComponent
+
+```javascript
+ReactComponent renderComponent(
+  ReactComponent component,
+  DOMElement container,
+  [function callback]
+)
+```
+
+Renders a React component into the DOM in the supplied `container`.
+
+If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
+
+If the optional callback is provided, it will be executed after the component is rendered or updated.
+
+
+### React.unmountAndReleaseReactRootNode
+
+```javascript
+unmountAndReleaseReactRootNode(DOMElement container)
+```
+
+Remove a mounted React component from the DOM and clean up its event handlers and state.
+
+
+### React.renderComponentToString
+
+```javascript
+renderComponentToString(ReactComponent component, function callback)
+```
+
+Render a component to its initial HTML. This should only be used on the server. React will call `callback` with an HTML string when the markup is ready. You can use this method to can 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.

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

@@ -0,0 +1,109 @@
+---
+id: component-api
+title: Component API
+layout: docs
+permalink: component-api.html
+prev: top-level-api.html
+next: component-specs.html
+---
+
+## ReactComponent
+
+Component classses 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} />
+    );
+  }
+});
+
+// <AvatarImage 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.
+
+
+### setState
+
+```javascript
+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.
+
+> Notes:
+>
+> *NEVER* mutate `this.state` directly, as calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
+>
+> `setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
+>
+> There is no guarantee of synchronous operation of calls to `setState` and calls may be batched for performance gains.
+
+
+### replaceState
+
+```javascript
+replaceState(object nextState[, function callback])
+```
+
+Like `setState()` but deletes any pre-existing state keys that are not in nextState.
+
+
+### forceUpdate()
+
+```javascript
+forceUpdate([function callback])
+```
+
+If your `render()` method reads from something other than `this.props` or `this.state`, you'll need to tell React when it needs to re-run `render()` by calling `forceUpdate()`. You'll also need to call `forceUpdate()` if you mutate `this.state` directly.
+
+Calling `forceUpdate()` will cause `render()` to be called on the component and its children, but React will still only update the DOM if the markup changes.
+
+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.

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

@@ -0,0 +1,176 @@
+---
+id: component-specs
+title: Component Specs and Lifecycle
+layout: docs
+permalink: component-specs.html
+prev: component-api.html
+next: tags-and-attributes.html
+---
+
+## Component Specifications
+
+When creating a component class by invoking `React.createClass()`, you should provide a specification object that contains a `render` method and can optionally contain other lifecycle methods described here.
+
+
+### render
+
+```javascript
+ReactComponent render()
+```
+
+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 native DOM component (such as `<div>`) or another composite component that you've defined yourself.
+
+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.
+
+
+### getInitialState
+
+```javascript
+object getInitialState()
+```
+
+Invoked once when the component is mounted. The return value will be used as the initial value of `this.state`.
+
+
+### getDefaultProps
+
+```javascript
+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).
+
+This method is invoked before `getInitialState` and therefore cannot rely on `this.state` or use `this.setState`.
+
+
+### propTypes
+
+```javascript
+object propTypes
+```
+
+The `propTypes` object allows you to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](reusable-components.html).
+
+<!-- TODO: Document propTypes here directly. -->
+
+
+### mixins
+
+```javascript
+array mixins
+```
+
+The `mixins` array allows you to use mixins to share behavior among multiple components. For more information about mixins, see [Reusable Components](reusable-components.html).
+
+<!-- TODO: Document mixins here directly. -->
+
+
+## Lifecycle Methods
+
+Various methods are executed at specific points in a component's lifecycle.
+
+
+### Mounting: componentWillMount
+
+```javascript
+componentWillMount()
+```
+
+Invoked immediately before 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
+
+```javascript
+componentDidMount(DOMElement rootNode)
+```
+
+Invoked immediately after rendering occurs. At this point in the lifecycle, the component has a DOM representation which you can access via the `rootNode` argument or by calling `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.
+
+
+### Updating: componentWillReceiveProps
+
+```javascript
+componentWillReceiveProps(object nextProps)
+```
+
+Invoked when a component is receiving new props. This method is not called for the initial render.
+
+Use this as an opportunity to react to a prop transition before `render()` is called by updating the state using `this.setState()`. The old props can be accessed via `this.props`. Calling `this.setState()` within this function will not trigger an additional render.
+
+```javascript
+componentWillReceiveProps: function(nextProps) {
+  this.setState({
+    likesIncreasing: nextProps.likeCount > this.props.likeCount
+  });
+}
+```
+
+> Note:
+>
+> There is no analogous method `componentWillReceiveState`. An incoming prop transition may cause a state change, but the opposite is not true. If you need to perform operations in response to a state change, use `componentWillUpdate`.
+
+
+### Updating: shouldComponentUpdate
+
+```javascript
+boolean shouldComponentUpdate(object nextProps, object nextState)
+```
+
+Invoked before rendering when new props or state are being received. This method is not called for the initial render or when `forceUpdate` is used.
+
+Use this as an opportunity to `return false` when you're certain that the
+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);
+}
+```
+
+If `shouldComponentUpdate` returns false, then `render()` will be completely skipped until the next state change. (In addition, `componentWillUpdate` and `componentDidUpdate` will not be called.)
+
+By default, `shouldComponentUpdate` always returns true to prevent subtle bugs when `state` is mutated in place, but if you are careful to always treat `state` as immutable and to read only from `props` and `state` in `render()` then you can override `shouldComponentUpdate` with an implementation that compares the old props and state to their replacements.
+
+If performance is a bottleneck, especially with dozens or hundreds of components, use `shouldComponentUpdate` to speed up your app.
+
+
+### Updating: componentWillUpdate
+
+```javascript
+componentWillUpdate(object nextProps, object nextState)
+```
+
+Invoked immediately before rendering when new props or state are being received. This method is not called for the initial render.
+
+Use this as an opportunity to perform preparation before an update occurs.
+
+> Note:
+>
+> You *cannot* use `this.setState()` in this method. If you need to update state in response to a prop change, use `componentWillReceiveProps` instead.
+
+
+### Updating: componentDidUpdate
+
+```javascript
+componentDidUpdate(object prevProps, object prevState, DOMElement rootNode)
+```
+
+Invoked immediately after updating occurs. This method is not called for the initial render.
+
+Use this as an opportunity to operate on the DOM when the component has been updated.
+
+
+### Unmounting: componentWillUnmount
+
+```javascript
+componentWillUnmount()
+```
+
+Invoked immediately before a component is unmounted from the DOM.
+
+Perform any necessary cleanup in this method, such as invalidating timers or cleaning up any DOM elements that were created in `componentDidMount`.

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

@@ -0,0 +1,65 @@
+---
+id: tags-and-attributes
+title: Tags and Attributes
+layout: docs
+permalink: tags-and-attributes.html
+prev: component-specs.html
+next: events.html
+---
+
+## Supported Tags
+
+React attempts to support all common elements. If you need an element that isn't listed here, please file an issue.
+
+The following elements are supported:
+
+
+### HTML Elements
+
+```
+a abbr address area article aside audio b base bdi bdo big blockquote body br
+button canvas caption cite code col colgroup data datalist dd del details dfn
+div dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6
+head header hr html i iframe img input ins kbd keygen label legend li link main
+map mark menu menuitem meta meter nav noscript object ol optgroup option output
+p param pre progress q rp rt ruby s samp script section select small source
+span strong style sub summary sup table tbody td textarea tfoot th thead time
+title tr track u ul var video wbr
+```
+
+### SVG elements
+
+```
+circle g line path polyline rect svg text
+```
+
+
+## Supported Attributes
+
+React supports all `data-*` and `aria-*` attributes as well as every attribute
+in the following lists. Note that all attributes are camel-cased and the attributes `class` and `for` are `className` and `htmlFor`, respectively, to match the DOM API specification.
+
+For a list of events, see [Supported Events](events.html).
+
+### HTML Attributes
+
+```
+accept accessKey action allowFullScreen allowTransparency alt autoCapitalize
+autoComplete autoFocus autoPlay cellPadding cellSpacing charSet checked
+className colSpan content contentEditable contextMenu controls data dateTime
+dir disabled draggable encType form frameBorder height hidden href htmlFor
+httpEquiv icon id label lang list max maxLength method min multiple name
+pattern placeholder poster preload radioGroup readOnly rel required role
+rowSpan scrollLeft scrollTop selected size spellCheck src step style tabIndex
+target title type value width wmode
+```
+
+In addition, the non-standard `autoCapitalize` attribute is supported for Mobile Safari.
+
+### 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
+```

docs/docs/ref-05-events.md

@@ -0,0 +1,205 @@
+---
+id: events
+title: Event System
+layout: docs
+permalink: events.html
+prev: tags-and-attributes.html
+next: dom-differences.html
+---
+
+## SyntheticEvent
+
+Your event handlers will be passed instances of `SyntheticEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event, including `stopPropagation()` and `preventDefault()`, except the events work identically across all browsers.
+
+If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it. Every `SyntheticEvent` object has the following attributes:
+
+```javascript
+boolean bubbles
+boolean cancelable
+DOMEventTarget currentTarget
+boolean defaultPrevented
+Number eventPhase
+boolean isTrusted
+DOMEvent nativeEvent
+void preventDefault()
+void stopPropagation()
+DOMEventTarget target
+Date timeStamp
+String type
+```
+
+
+## Supported Events
+
+React normalizes events so that they have consistent properties across
+different browsers.
+
+
+### Clipboard Events
+
+Event names:
+
+```
+onCopy onCut onPaste
+```
+
+Properties:
+
+```javascript
+DOMDataTransfer clipboardData
+```
+
+
+### Keyboard Events
+
+Event names:
+
+```
+onKeyDown onKeyPress onKeyUp
+```
+
+Properties:
+
+```javascript
+boolean altKey
+String char
+boolean ctrlKey
+String key
+String locale
+Number location
+boolean metaKey
+boolean repeat
+boolean shiftKey
+```
+
+
+### Focus Events
+
+Event names:
+
+```
+onFocus onBlur
+```
+
+Properties:
+
+```javascript
+DOMEventTarget relatedTarget
+```
+
+
+### Form Events
+
+Event names:
+
+```
+onChange onInput onSubmit
+```
+
+For more information about the onChange event, see [Forms](forms.html).
+
+
+### Mouse Events
+
+Event names:
+
+```
+onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave
+onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave
+onMouseMove onMouseUp
+```
+
+Properties: 
+
+```javascript
+boolean altKey
+Number button
+Number buttons
+Number clientX
+Number clientY
+boolean ctrlKey
+boolean metaKey
+Number pageX
+Number pageY
+DOMEventTarget relatedTarget
+Number screenX
+Number screenY
+boolean shiftKey
+```
+
+
+### Mutation Events
+
+Event names:
+
+```
+onDOMCharacterDataModified
+```
+
+Properties:
+
+```javascript
+Number attrChange
+String attrName
+String newValue
+String prevValue
+Node relatedNode
+```
+
+
+### Touch events
+
+To enable touch events, call `React.initializeTouchEvents(true)` before
+rendering any component.
+
+Event names:
+
+```
+onTouchCancel onTouchEnd onTouchMove onTouchStart
+```
+
+Properties:
+
+```javascript
+boolean altKey
+DOMTouchList changedTouches
+boolean ctrlKey
+boolean metaKey
+boolean shiftKey
+DOMTouchList targetTouches
+DOMTouchList touches
+```
+
+
+### UI Events
+
+Event names:
+
+```
+onScroll
+```
+
+Properties:
+
+```javascript
+Number detail
+DOMAbstractView view
+```
+
+
+### Wheel Events
+
+Event names:
+
+```
+onWheel
+```
+
+Properties:
+
+```javascript
+Number deltaX
+Number deltaMode
+Number deltaY
+Number deltaZ
+```

docs/docs/ref-06-dom-differences.md

@@ -0,0 +1,14 @@
+---
+id: dom-differences
+title: DOM Differences
+layout: docs
+permalink: dom-differences.html
+prev: events.html
+---
+
+React has implemented a browser-independent events and DOM system for performance and cross-browser compatibility reasons. We took the opportunity to clean up a few rough edges in browser DOM implementations.
+
+* All DOM properties and attributes (including event handlers) should be camelCased to be consistent with standard JavaScript style. We intentionally break with the spec here since the spec is inconsistent.
+* The `style` attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM `style` JavaScript property, is more efficient, and prevents XSS security holes.
+* All event objects conform to the W3C spec, and all events (including submit) bubble correctly per the W3C spec. See [Event System](events.html) for more details.
+* The `onChange` event behaves as you would expect it to: whenever a form field is changed this event is fired rather than inconsistently on blur. We intentionally break from existing browser behavior because `onChange` is a misnomer for its behavior and React relies on this event to react to user input in real time. See [Forms](forms.html) for more details.

docs/docs/reference.html

@@ -0,0 +1,4 @@
+---
+layout: redirect
+destination: top-level-api.html
+---

docs/docs/tutorial.md

@@ -1,11 +1,8 @@
 ---
-id: docs-tutorial
+id: tutorial
 title: Tutorial
 layout: docs
-prev: getting-started.html
-next: common-questions.html
 ---
-
 We'll be building a simple, but realistic comments box that you can drop into a blog, similar to Disqus, LiveFyre or Facebook comments.
 
 We'll provide:
@@ -20,11 +17,11 @@ It'll also have a few neat features:
 * **Live updates:** as other users comment we'll pop them into the comment view in real time
 * **Markdown formatting:** users can use Markdown to format their text
 
-## Want to skip all this and just see the source?
+### Want to skip all this and just see the source?
 
 [It's all on GitHub.](https://github.com/petehunt/react-tutorial)
 
-## Getting started
+### Getting started
 
 For this tutorial we'll use prebuilt JavaScript files on a CDN. Open up your favorite editor and create a new HTML document:
 
@@ -50,7 +47,7 @@ For this tutorial we'll use prebuilt JavaScript files on a CDN. Open up your fav
 
 For the remainder of this tutorial, we'll be writing our JavaScript code in this script tag.
 
-## Your first component
+### Your first component
 
 React is all about modular, composable components. For our comment box example, we'll have the following component structure:
 
@@ -80,7 +77,7 @@ React.renderComponent(
 );
 ```
 
-### JSX Syntax
+#### JSX Syntax
 
 The first thing you'll notice is the XML-ish syntax in your JavaScript. We have a simple precompiler that translates the syntactic sugar to this plain JavaScript:
 
@@ -102,19 +99,19 @@ React.renderComponent(
 );
 ```
 
-Its use is optional but we've found JSX syntax easier to use than plain JavaScript. Read more on the [JSX Syntax article](syntax.html).
+Its use is optional but we've found JSX syntax easier to use than plain JavaScript. Read more on the [JSX Syntax article](jsx-in-depth.html).
 
-### What's going on
+#### What's going on
 
 We pass some methods in a JavaScript object to `React.createClass()` to create a new React component. The most important of these methods is called `render` which returns a tree of React components that will eventually render to HTML.
 
 The `<div>` tags are not actual DOM nodes; they are instantiations of React `div` components. You can think of these as markers or pieces of data that React knows how to handle. React is **safe**. We are not generating HTML strings so XSS protection is the default.
 
-You do not have to return basic HTML. You can return a tree of components that you (or someone else built). This is what makes React **composable**: a key tenet of maintainable frontends.
+You do not have to return basic HTML. You can return a tree of components that you (or someone else) built. This is what makes React **composable**: a key tenet of maintainable frontends.
 
 `React.renderComponent()` instantiates the root component, starts the framework, and injects the markup into a raw DOM element, provided as the second argument.
 
-# Composing components
+## Composing components
 
 Let's build skeletons for `CommentList` and `CommentForm` which will, again, be simple `<div>`s:
 
@@ -160,7 +157,7 @@ var CommentBox = React.createClass({
 
 Notice how we're mixing HTML tags and components we've built. HTML components are regular React components, just like the ones you define, with one difference. The JSX compiler will automatically rewrite HTML tags to "React.DOM.tagName" expressions and leave everything else alone. This is to prevent the pollution of the global namespace.
 
-## Component Properties
+### Component Properties
 
 Let's create our third component, `Comment`. We will want to pass it the author name and comment text so we can reuse the same code for each unique comment. First let's add some comments to the `CommentList`:
 
@@ -180,7 +177,7 @@ var CommentList = React.createClass({
 
 Note that we have passed some data from the parent `CommentList` component to the child `Comment` component as both XML-like children and attributes. Data passed from parent to child is called **props**, short for properties.
 
-## Using props
+### Using props
 
 Let's create the Comment component. It will read the data passed to it from the CommentList and render some markup:
 
@@ -202,11 +199,21 @@ var Comment = React.createClass({
 
 By surrounding a JavaScript expression in braces inside JSX (as either an attribute or child), you can drop text or React components into the tree. We access named attributes passed to the component as keys on `this.props` and any nested elements as `this.props.children`.
 
-## Adding Markdown
+### Adding Markdown
 
 Markdown is a simple way to format your text inline. For example, surrounding text with asterisks will make it emphasized.
 
-First, add the third-party **Showdown** library to your application. This is a JavaScript library which takes Markdown text and converts it to raw HTML. This requires a script tag in your head (which we have already included in the React playground).
+First, add the third-party **Showdown** library to your application. This is a JavaScript library which takes Markdown text and converts it to raw HTML. This requires a script tag in your head (which we have already included in the React playground):
+
+```html{6}
+<!-- template.html -->
+<head>
+  <title>Hello React</title>
+  <script src="http://fb.me/react-{{site.react_version}}.js"></script>
+  <script src="http://fb.me/JSXTransformer-{{site.react_version}}.js"></script>
+  <script src="http://cdnjs.cloudflare.com/ajax/libs/showdown/0.3.1/showdown.min.js"></script>
+</head>
+```
 
 Next, let's convert the comment text to Markdown and output it:
 
@@ -255,15 +262,15 @@ This is a special API that intentionally makes it difficult to insert raw HTML,
 
 **Remember:** by using this feature you're relying on Showdown to be secure.
 
-## Hook up the data model
+### Hook up the data model
 
 So far we've been inserting the comments directly in the source code. Instead, let's render a blob of JSON data into the comment list. Eventually this will come from the server, but for now, write it in your source:
 
 ```javascript
 // tutorial8.js
 var data = [
-  {author: 'Pete Hunt', text: 'This is one comment'},
-  {author: 'Jordan Walke', text: 'This is *another* comment'}
+  {author: "Pete Hunt", text: "This is one comment"},
+  {author: "Jordan Walke", text: "This is *another* comment"}
 ];
 ```
 
@@ -309,7 +316,7 @@ var CommentList = React.createClass({
 
 That's it!
 
-## Fetching from the server
+### Fetching from the server
 
 Let's replace the hard-coded data with some dynamic data from the server. We will remove the data prop and replace it with a URL to fetch:
 
@@ -317,13 +324,13 @@ Let's replace the hard-coded data with some dynamic data from the server. We wil
 // tutorial11.js
 React.renderComponent(
   <CommentBox url="comments.json" />,
-  document.getElementById('example')
+  document.getElementById('content')
 );
 ```
 
 This component is different from the prior components because it will have to re-render itself. The component won't have any data until the request from the server comes back, at which point the component may need to render some new comments.
 
-## Reactive state
+### Reactive state
 
 So far, each component has rendered itself once based on its props. `props` are immutable: they are passed from the parent and are "owned" by the parent. To implement interactions, we introduce mutable **state** to the component. `this.state` is private to the component and can be changed by calling `this.setState()`. When the state is updated, the component re-renders itself.
 
@@ -351,14 +358,14 @@ var CommentBox = React.createClass({
 
 `getInitialState()` executes exactly once during the lifecycle of the component and sets up the initial state of the component.
 
-### Updating state
+#### Updating state
 When the component is first created, we want to GET some JSON from the server and update the state to reflect the latest data. In a real application this would be a dynamic endpoint, but for this example, we will use a static JSON file to keep things simple:
 
 ```javascript
 // tutorial13.json
 [
-  {'author': 'Pete Hunt', 'text': 'This is one comment'},
-  {'author': 'Jordan Walke', 'text': 'This is *another* comment'}
+  {"author": "Pete Hunt", "text": "This is one comment"},
+  {"author": "Jordan Walke", "text": "This is *another* comment"}
 ]
 ```
 
@@ -435,13 +442,13 @@ React.renderComponent(
 
 ```
 
-All we have done here is move the AJAX call to a separate method and call it when the component is first loaded and every 60 seconds after that. Try running this in your browser and changing the `comments.json` file; within 5 seconds, the changes will show!
+All we have done here is move the AJAX call to a separate method and call it when the component is first loaded and every 5 seconds after that. Try running this in your browser and changing the `comments.json` file; within 5 seconds, the changes will show!
 
-## Adding new comments
+### Adding new comments
 
 Now it's time to build the form. Our `CommentForm` component should ask the user for their name and comment text and send a request to the server to save the comment.
 
-```javascript{5-8}
+```javascript{5-9}
 // tutorial15.js
 var CommentForm = React.createClass({
   render: function() {
@@ -461,7 +468,7 @@ Let's make the form interactive. When the user submits the form, we should clear
 ```javascript{3-13,16,21}
 // tutorial16.js
 var CommentForm = React.createClass({
-  handleSubmit: React.autoBind(function() {
+  handleSubmit: function() {
     var author = this.refs.author.getDOMNode().value.trim();
     var text = this.refs.text.getDOMNode().value.trim();
     if (!text || !author) {
@@ -471,7 +478,7 @@ var CommentForm = React.createClass({
     this.refs.author.getDOMNode().value = '';
     this.refs.text.getDOMNode().value = '';
     return false;
-  }),
+  },
   render: function() {
     return (
       <form class="commentForm" onSubmit={this.handleSubmit}>
@@ -488,19 +495,17 @@ var CommentForm = React.createClass({
 });
 ```
 
-#### Events
+##### Events
 
 React attaches event handlers to components using a camelCase naming convention. We attach an `onSubmit` handler to the form that clears the form fields when the form is submitted with valid input.
 
-We always return `false` from the event handler to prevent the browser's default action of submitting the form. (If you prefer, you can instead take the event as an argument and call `preventDefault()` on it &ndash; read more about [event handling](event-handling.html).)
+We always return `false` from the event handler to prevent the browser's default action of submitting the form. (If you prefer, you can instead take the event as an argument and call `preventDefault()` on it.)
 
-`React.autoBind()` is a simple way to ensure that a method is always bound to its component. Inside the method, `this` will be bound to the component instance.
-
-#### Refs
+##### Refs
 
 We use the `ref` attribute to assign a name to a child component and `this.refs` to reference the component. We can call `getDOMNode()` on a component to get the native browser DOM element.
 
-#### Callbacks as props
+##### Callbacks as props
 
 When a user submits a comment, we will need to refresh the list of comments to include the new one. It makes sense to do all of this logic in `CommentBox` since `CommentBox` owns the state that represents the list of comments.
 
@@ -519,9 +524,9 @@ var CommentBox = React.createClass({
       }.bind(this)
     });
   },
-  handleCommentSubmit: React.autoBind(function(comment) {
+  handleCommentSubmit: function(comment) {
     // TODO: submit to the server and refresh the list
-  }),
+  },
   getInitialState: function() {
     return {data: []};
   },
@@ -551,14 +556,14 @@ Let's call the callback from the `CommentForm` when the user submits the form:
 ```javascript{6}
 // tutorial18.js
 var CommentForm = React.createClass({
-  handleSubmit: React.autoBind(function() {
+  handleSubmit: function() {
     var author = this.refs.author.getDOMNode().value.trim();
     var text = this.refs.text.getDOMNode().value.trim();
     this.props.onCommentSubmit({author: author, text: text});
     this.refs.author.getDOMNode().value = '';
     this.refs.text.getDOMNode().value = '';
     return false;
-  }),
+  },
   render: function() {
     return (
       <form class="commentForm" onSubmit={this.handleSubmit}>
@@ -590,7 +595,7 @@ var CommentBox = React.createClass({
       }.bind(this)
     });
   },
-  handleCommentSubmit: React.autoBind(function(comment) {
+  handleCommentSubmit: function(comment) {
     $.ajax({
       url: this.props.url,
       data: comment,
@@ -600,7 +605,7 @@ var CommentBox = React.createClass({
         this.setState({data: data});
       }.bind(this)
     });
-  }),
+  },
   getInitialState: function() {
     return {data: []};
   },
@@ -625,7 +630,7 @@ var CommentBox = React.createClass({
 });
 ```
 
-## Optimization: optimistic updates
+### Optimization: optimistic updates
 
 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.
 
@@ -642,7 +647,7 @@ var CommentBox = React.createClass({
       }.bind(this)
     });
   },
-  handleCommentSubmit: React.autoBind(function(comment) {
+  handleCommentSubmit: function(comment) {
     var comments = this.state.data;
     comments.push(comment);
     this.setState({data: comments});
@@ -655,7 +660,7 @@ var CommentBox = React.createClass({
         this.setState({data: data});
       }.bind(this)
     });
-  }),
+  },
   getInitialState: function() {
     return {data: []};
   },
@@ -680,6 +685,6 @@ var CommentBox = React.createClass({
 });
 ```
 
-## Congrats!
+### Congrats!
 
-You have just built a comment box in a few simple steps. Learn more about React in the [reference](syntax.html) or start hacking! Good luck!
+You have just built a comment box in a few simple steps. Learn more about [why to use React](why-react.html), or dive into the [API reference](top-level-api.html) and start hacking! Good luck!

docs/downloads.md

@@ -29,12 +29,14 @@ The uncompressed, development version of React core with inline documentation.
 ```
 
 #### <a href="http://fb.me/JSXTransformer-{{site.react_version}}.js">JSX Transform</a>
-The JSX transformer used to support [XML syntax](/react/docs/syntax.html) in JavaScript.
+The JSX transformer used to support [XML syntax](/react/docs/jsx-in-depth.html) in JavaScript.
 
 ```html
 <script src="http://fb.me/JSXTransformer-{{site.react_version}}.js"></script>
 ```
 
+All scripts are also available via [CDNJS](http://cdnjs.com/#react).
+
 ## Bower
 
 ```sh
@@ -47,14 +49,3 @@ $ bower install --save react
 $ npm install -g react-tools
 ```
 
-## Release Notes
-
-**0.3.2** Improve compatibility of JSX Transformer; make `react-tools` compatible with [browserify](https://github.com/substack/node-browserify)
-
-**0.3.1** Fix `react-tools` module
-
-**0.3** Initial public release.
-
-**0.2** Standardize API & refactor component lifecycle. Normalize DOM interactions.
-
-**0.1** Initial release.

docs/index.md

@@ -56,10 +56,11 @@ id: home
     <div class="example">
       <h3>An Application</h3>
       <p>
-        Using properties and state, we can put together a small Todo
-        application. React provides an interface to the DOM via `refs`. Although
-        event handlers appear to be rendered inline, they will be
-        collected and implemented using event delegation.
+        Using `props` and `state`, we can put together a small Todo application.
+        This example uses `state` to track the current list of items as well as
+        the text that the user has entered. Although event handlers appear to be
+        rendered inline, they will be collected and implemented using event
+        delegation. 
       </p>
       <div id="todoExample"></div>
     </div>

docs/jsx-compiler.md

@@ -6,7 +6,7 @@ id: jsx-compiler
 <div class="jsxCompiler">
   <h1>JSX Compiler</h1>
   <p>
-    This tool demonstrates how <a href="/react/docs/syntax.html">JSX syntax</a>
+    This tool demonstrates how <a href="/react/docs/jsx-in-depth.html">JSX syntax</a>
     is desguared into native JavaScript.
   </p>
   <div id="jsxCompiler"></div>

docs/support.md

@@ -6,10 +6,20 @@ id: support
 
 **React** is worked on full-time by Facebook's product infrastructure and Instagram's user interface engineering teams. They're often around and available for questions.
 
+## Stack Overflow
+
+Many members of the community use Stack Overflow to ask questions. Read through the [existing questions](http://stackoverflow.com/questions/tagged/reactjs) tagged with **reactjs** or [ask your own](http://stackoverflow.com/questions/ask)!
+
 ## Google Groups mailing list
 
-<a href="http://groups.google.com/group/reactjs" target="_blank">The **reactjs** Google Group</a> is the best place to ask questions and find answers.
+<a href="http://groups.google.com/group/reactjs" target="_blank">The **reactjs** Google Group</a> is also a good place to ask questions and find answers.
 
 ## IRC
 
 Many developers and users idle on Freenode.net's IRC network in **[#reactjs on freenode](irc://chat.freenode.net/reactjs)**.
+
+## Twitter
+
+[**#reactjs** hash tag on Twitter](https://twitter.com/search?q=%23reactjs) is used to keep up with the latest React news.
+
+<center><a class="twitter-timeline" data-dnt="true" data-chrome="nofooter noheader transparent" href="https://twitter.com/search?q=%23reactjs" data-widget-id="342522405270470656"></a></center>

examples/ballmer-peak/example.js

@@ -14,9 +14,9 @@ var BallmerPeakCalculator = React.createClass({
   getInitialState: function() {
     return {bac: 0};
   },
-  handleChange: React.autoBind(function() {
-    this.setState({bac: this.refs.bac.getDOMNode().value});
-  }),
+  handleChange: function(event) {
+    this.setState({bac: event.target.value});
+  },
   render: function() {
     var bac;
     var pct;
@@ -33,7 +33,7 @@ var BallmerPeakCalculator = React.createClass({
         <h4>Compute your Ballmer Peak:</h4>
         <p>
           If your BAC is{' '}
-          <input ref="bac" type="text" onKeyUp={this.handleChange} value={this.state.bac} />
+          <input type="text" onChange={this.handleChange} value={this.state.bac} />
           {', '}then <b>{pct}</b> of your lines of code will have bugs.
         </p>
       </div>

examples/ballmer-peak/index.html

@@ -14,7 +14,7 @@
         <pre>
           python -m SimpleHTTPServer
         </pre>
-        and going to <a href="http://localhost:8080/">http://localhost:8080/</a>.
+        and going to <a href="http://localhost:8000/">http://localhost:8000/</a>.
       </p>
     </div>
     <h4>Example Details</h4>

examples/basic-jsx-external/index.html

@@ -54,7 +54,7 @@
             <pre id="chromeServerCLI" class="codeBox">
 cd /Path/To/This/File
 python -m SimpleHTTPServer
-open -a "Google Chrome"  <a href="http://localhost:8080/">http://localhost:8080/</a>.  </pre>
+open -a "Google Chrome"  <a href="http://localhost:8000/">http://localhost:8000/</a>.  </pre>
           </li>
         </ol>
         <h4 id="chromeErrorFooter" style="color: #733"></h4>