more scaling up

docs/refactor/00-table-of-contents.md

@@ -30,10 +30,11 @@ Handling user input
 Scaling up: using multiple components
 - Motivation: separate concerns
 - Composition example
-- Ownership
+- Ownership (and owner vs. parent)
 - Data flow (one-way data binding)
 - A note on performance
 - You should build a reusable component library (CSS, testing etc)
+- Prop validation
 - Mixins
 - Testing
 
@@ -42,9 +43,10 @@ Forms
 - How to think about Reactive forms
 - New form events and properties
 
-Touching the DOM
+Working with the browser
 - Refs / getDOMNode()
 - Component lifecycle
+- Polyfills
 
 Integrating with other UI libraries
 - Using jQuery plugins
@@ -64,6 +66,7 @@ Big ideas
 - Bootstrap bindings (responsive grids)
 - Reactive CSS
 - Web workers
+- Native views
 
 Case studies
 - Comment box tutorial from scratch

docs/refactor/01-motivation.md

@@ -6,7 +6,7 @@ We built React to solve one problem: **building large applications with data tha
 
 ## Stay simple and declarative
 
-React apps are easy to write. Think of your UI as a state machine; simply express how the UI should look at any given point in time, and React will manage all UI updates for you when your underlying data changes.
+React apps are easy to write. Simply express how the UI should look at any given point in time, and React will manage all UI updates for you when your underlying data changes.
 
 It's just like writing a server-rendered web app: when the data changes, React conceptually hits the refresh button, except React is very fast and maintains the state of your UI. Because of this, React's API is very small and easy to understand.
 

docs/refactor/02-displaying-data.md

@@ -59,10 +59,12 @@ The inputs to this component are called `props` -- short for "properties". They'
 
 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.
 
+**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. This is a limitation we can fix, but we have not identified a pressing reason to do so yet; reach out to our [Google Group](http://groups.google.com/group/reactjs) if you have a compelling case for it.
+
 ## 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 is very small; the example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.md)
+JSX is very small; the example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.md).

docs/refactor/03-handling-user-input.md

@@ -46,6 +46,8 @@ Under the hood React does a few things to keep your code performant and easy to
 
 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 state tends to be so minimal.

docs/refactor/04-scaling-up.md

@@ -4,12 +4,80 @@ So far, we've looked at how to write a single component to display data and hand
 
 ## Motivation: separation of concerns
 
-By building modular components that reuse other components using well-definted 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.
+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 distinciton 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.
+
+## 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 API docs](./api.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.
+
+## Build reusable component libraries!
+
+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 using `propTypes`.
+
+** TODO zpao **
+
+## 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. React provides [lifecycle methods](./06-working-with-the-browser.html)