doc(lifecycles): WIP document lifecycle

current/en-us/3. fundamentals/2. creating-components.md

@@ -89,18 +89,31 @@ export class CustomerDetail {
 
 ## The Component Lifecycle
 
-All components have a well-defined lifecycle. Below is a list of methods you can implement on your view-model in order to hook into the component lifecycle:
+Every component instance has a lifecycle that you can tap into. This makes it easy for you to perform various actions at particular times. For example, you may want to execute some code as soon as your component properties are bound, but before the component is first rendered. Or, you may want to run some code to manipulate the DOM as soon as possible after your element is attached to the document. Below is a summary of the various lifecycle callbacks that you can hook into in your component.
+
+| Lifecycle Callback | Description |
+| :--- | :--- |
+| `constructor` | When the framework instantiates a component, it calls your class's constructor, just like any JavaScript class. This is the best place to put basic initialization code that is not dependent on bindable properties. |
+| `created` | The "created" hook runs just after the constructor and can be treated very similarly. The only difference is that the component's `Controller` has been instantiated and is accessible through the `$controller` property, for advanced scenarios. |
+| `bind`    | If your component has a method named "bind", then the framework will invoke it when it has begun binding values to your bindable properties. In terms of the component hierarchy, the bind hooks execute top-down, from parent to child, so your bindables will have their values set by the owning components, but the bindings in your view are not yet set. This is a good place to perform any work or make changes to anything that your view would depend on because data still flows down synchronously. This is the best time to do anything that might affect children as well. |
+| `attached` | If your component has a method named "attached", then the framework will invoke it when it has fully attached your HTML element to the document, along with its children. In terms of the component hierarchy, the attached hooks execute top-down. |
+| `detached` | If your component has a method named "detached", then the framework will invoke it when it has fully removed your HTML element from the document. In terms of the component hierarchy, the detached hooks execute bottom-up. |
+| `unbind` | If your component has a method named "unbind", then the framework will invoke it when it has fully disconnected bindings from your component. In terms of the component hierarchy, the unbind hooks execute bottom-up. |
+
+To tap into any of these hooks, simply implement the method on your class.
+
+<div style="border: thick solid red; border-radius: 12px; padding: 16px;">
+<span style="text-align: center; font-size: 16pt;"><b>TODO</b></span>
+These have value, providing the method signatures, the new v2 documentation does not. I'm not sure if that is intentional or whether the signatures have changed.
+</div>
 
-1. `constructor()` - The view-model's constructor is called first.
 2. `created(owningView: View, myView: View)` - If the view-model implements the `created` callback it is invoked next. At this point in time, the view has also been created and both the view-model and the view are connected to their controller. The created callback will receive the instance of the "owningView". This is the view that the component is declared inside of. If the component itself has a view, this will be passed second.
 3. `bind(bindingContext: Object, overrideContext: Object)` - Databinding is then activated on the view and view-model. If the view-model has a `bind` callback, it will be invoked at this time. The "binding context" to which the component is being bound will be passed first. An "override context" will be passed second. The override context contains information used to traverse the parent hierarchy and can also be used to add any contextual properties that the component wants to add.
-4. `attached()` - Next, the component is attached to the DOM (in document). If the view-model has an `attached` callback, it will be invoked at this time.
-5. `detached()` - If defined on your view-model - is invoked after the component has been removed from the DOM. Due to navigating away or other reasons.
-6. `unbind()` - After a component is detached, it's usually unbound. If your view-model has the `unbind` callback, it will be invoked during this process.
 
-Each of these callbacks is optional. Implement whatever makes sense for your component, but don't feel obligated to implement any of them if they aren't needed for your scenario. Usually, if you implement `bind` you will need to implement `unbind`. The same goes for `attached` and `detached`, but again, it isn't mandatory.
+Every lifecycle callback is optional. Implement whatever makes sense for your component, but don't feel obligated to implement any of them if they aren't needed for your scenario. Some of the lifecycle callbacks make sense to implement in pairs (`bind/unbind`, `attached/detached`) in order to clean up any resources you have allocated. If you registered a listener or subscriber remember to remove them.
 
-The order in which the lifecycle hooks are listed above matches the order in which they are invoked. For example, `bind` happens before `attached` to ensure elements take their initial state from the view-model before the view is attached to the DOM and transitioned in. Likewise, `detached` happens before `unbind` to ensure the view is transitioned out and detached from the DOM before `unbind` potentially causes the view to change.
+[Aurelia Lifecycle Demo](https://codesandbox.io/embed/aurelia-lifecycle-demo-yy1tc?expanddevtools=1&autoresize=1&fontsize=18&hidenavigation=1&module=%2Fsrc%2Fapp.html&view=preview)
 
 > Info
 > It is important to note that if you implement the `bind` callback function, then the property changed callbacks for any `bindable` properties will not be called when the property value is initially set. The changed callback will be called for any subsequent time the bound value changes.
+