Initial pass at animations and transitions docs

docs/_config.yml

@@ -51,5 +51,7 @@ nav_docs_sections:
       title: More About Refs
   - id: tooling-integration
     title: Tooling Integration
+  - id: addons
+    title: Add-ons
   - id: reference
     title: Reference

docs/docs/08-tooling-integration.md

@@ -4,7 +4,7 @@ title: Tooling Integration
 layout: docs
 permalink: tooling-integration.html
 prev: more-about-refs.html
-next: reference.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.

docs/docs/09-addons.md

@@ -0,0 +1,93 @@
+---
+id: addons
+title: Add-ons
+layout: docs
+permalink: addons.html
+prev: tooling-integration.html
+next: reference.html
+---
+
+## 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. **TODO: how do we import this?**
+
+```javascript{22-24}
+/** @jsx React.DOM */
+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});
+  },
+  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!

docs/docs/09-reference.md → docs/docs/10-reference.md

@@ -3,7 +3,7 @@ id: reference
 title: Reference
 layout: docs
 permalink: reference.html
-prev: tooling-integration.html
+prev: addons.html
 ---
 
 ## Examples
@@ -13,14 +13,14 @@ prev: tooling-integration.html
 
 * 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 its question editor.
+* [Khan Academy](http://khanacademy.org/) is using React for several products in production.
 
 
 ### 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/).
-* [reactapp](https://github.com/jordwalke/reactapp) is a simple app template to get you up-and-running quickly with React.
+* [react-page](https://github.com/facebook/react-page) is a simple app template to get you up-and-running quickly with React.
 * [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.