add initState, rename animated_container

sky/sdk/lib/widgets/README.md

 Sky Widgets
 ===========
 
 Sky widgets are built using a functional-reactive framework, which takes
 inspiration from [React](http://facebook.github.io/react/). The central idea is
 that you build your UI out of components. Components describe what their view
 should look like given their current configuration and state. When a component's
 state changes, the component rebuilds its description, which the framework diffs
 against the previous description in order to determine the minial changes needed
 in the underlying render tree to transition from one state to the next.
@@ skipping 317 matching lines @@
    of `RenderObjects` that matches the description. When the framework calls
    `build` again, the component still returns a fresh description of its
    appearence, but this time the framework compares the new description with the
    previous description and makes the minimal modifications to the underlying
    `RenderObjects` to make them match the new description.
 
    In this process, old stateless components are discarded and the new stateless
    components created by the parent component are retained in the widget
    hierchy. Old _stateful_ components, however, cannot simply be discarded
    because they contain state that needs to be preserved. Instead, the old
-   stateful components are retained in the widget hiearchy and asked to
+   stateful components are retained in the widget hierarchy and asked to
    `syncFields` with the new instance of the component created by the parent in
    its `build` function.
 
    Without `syncFields`, the new values the parent component passed to the
    `MyDialog` constructor in the parent's `build` function would be lost because
    they would be stored only as member variables on the new instance of the
    component, which is not retained in the component hiearchy. Therefore, the
    `syncFields` function in a component should update `this` to account for the
    new values the parent passed to `source` because `source` is the authorative
    source of those values.
@@ skipping 30 matching lines @@
 instance into the widget heiarchy. (Instead of mounting later instances, the
 framework passes them to the original instance in `syncFields` so that the first
 instance of the component can incorporate the values passed by the parent to the
 component's constructor.)
 
 Components often override `didUnmount` to release resources or to cancel
 subscriptions to event streams from outside the widget hierachy. When overriding
 either `didMount` or `didUnmount`, a component should call its superclass's
 `didMount` or `didUnmount` function.
 
+initState
+---------
+
+The framework calls the `initState` function on stateful components before
+building them. The default implementation of initState does nothing. If your
+component requires non-trivial work to initialize its state, you should
+override initState and do it there rather than doing it in the stateful
+component's constructor. If the component doesn't need to be built (for
+example, if it was constructed just to have its fields synchronized with
+an existing stateful component) you'll avoid unnecessary work. Also, some
+operations that involve interacting with the widget hierarchy cannot be
+done in a component's constructor.
+
+When overriding `initState`, a component should call its superclass's 
+`initState` function.
+
 Keys
 ----
 
 If a component requires fine-grained control over which widgets sync with each
 other, the component can assign keys to the widgets it builds. Without keys, the
 framework matches widgets in the current and previous build according to their
 `runtimeType` and the order in which they appear. With keys, the framework
 requires that the two widgets have the same `key` as well as the same
 `runtimeType`.
 
@@ skipping 14 matching lines @@
 
 Dependencies
 ------------
 
  * `package:vector_math`
  * [`package:sky/animation`](../animation)
  * [`package:sky/base`](../base)
  * [`package:sky/painting`](../painting)
  * [`package:sky/rendering`](../rendering)
  * [`package:sky/theme`](../theme)