Merge pull request #1059 from petehunt/rtg-docs

Document ReactCSSTransitionGroup

Author: petehunt

docs/docs/09.1-animation.md

@@ -7,16 +7,20 @@ prev: addons.html
 next: two-way-binding-helpers.html
 ---
 
-`ReactTransitions` is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
+React provides a `ReactTransitionGroup` addon component as a low-level API for animation, and a `ReactCSSTransitionGroup` for easily implementing basic CSS animations and transitions.
 
-## Getting Started
+## High-level API: `ReactCSSTransitionGroup`
 
-`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.
+`ReactCSSTransitionGroup` is based on `ReactTransitionGroup` and is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
+
+### Getting Started
+
+`ReactCSSTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.
 
 ```javascript{22-24}
 /** @jsx React.DOM */
 
-var ReactTransitionGroup = React.addons.TransitionGroup;
+var ReactCSSTransitionGroup = React.addons.TransitionGroup;
 
 var TodoList = React.createClass({
   getInitialState: function() {
@@ -43,16 +47,16 @@ var TodoList = React.createClass({
     return (
       <div>
         <div><button onClick={this.handleAdd} /></div>
-        <ReactTransitionGroup transitionName="example">
+        <ReactCSSTransitionGroup transitionName="example">
           {items}
-        </ReactTransitionGroup>
+        </ReactCSSTransitionGroup>
       </div>
     );
   }
 });
 ```
 
-In this component, when a new item is added to `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.
+In this component, when a new item is added to `ReactCSSTransitionGroup` 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:
 
@@ -67,7 +71,7 @@ You can use these classes to trigger a CSS animation or transition. For example,
 }
 ```
 
-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 with add-ons 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:
+You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keeps it in the DOM. If you're using an unminified build of React with add-ons you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactCSSTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS:
 
 ```css
 .example-leave {
@@ -80,18 +84,36 @@ You'll notice that when you try to remove an item `ReactTransitionGroup` keeps i
 }
 ```
 
-## Disabling Animations
+### 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 `ReactCSSTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactCSSTransitionGroup` to disable these animations.
+
+## Low-level API: `ReactTransitionGroup`
+
+`ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.
+
+### `componentWillEnter(callback)`
+
+This is called at the same time as `componentDidMount()` for components added to an existing `TransitionGroup`. It will block other animations from occurring until `callback` is called. It will not be called on the initial render of a `TransitionGroup`.
+
+### `componentDidEnter()`
+
+This is called after the `callback` function that was passed to `componentWillEnter` is called.
+
+### `componentWillLeave(callback)`
+
+This is called when the child has been removed from the `ReactTransitionGroup`. Though the child has been removed, `ReactTransitionGroup` will keep it in the DOM until `callback` is called.
+
+### `componentDidLeave()`
 
-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.
+This is called when the `willLeave` `callback` is called (at the same time as `componentWillUnmount`).
 
-## Rendering a Different Component
+### 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}>
+```javascript{1}
+<ReactTransitionGroup component={React.DOM.ul}>
   ...
 </ReactTransitionGroup>
 ```

src/browser/ReactWithAddons.js

@@ -29,6 +29,7 @@ var LinkedStateMixin = require('LinkedStateMixin');
 var React = require('React');
 var ReactCSSTransitionGroup = require('ReactCSSTransitionGroup');
 var ReactTransitionGroup = require('ReactTransitionGroup');
+var ReactCSSTransitionGroup = require('ReactCSSTransitionGroup');
 
 var cx = require('cx');
 var cloneWithProps = require('cloneWithProps');