document all the hooks!

Author: yyx990803

docs/pipeline/activate.md

@@ -0,0 +1,21 @@
+# `activate(transition) [-> Promise]`
+
+Called on an incoming component during the activation phase when it is created and about to get transitioned in.
+
+### Arguments
+
+- `transition`
+
+  Call `transition.next()` to resolve the hook. Note calling `transition.abort()` here will not take the app back to the previous route because the transition has already been validated.
+
+### Return Value
+
+- Optionally return a Promise.
+  - `resolve` -> `transition.next()`
+  - `reject(reason)` -> `transition.abort(reason)`
+
+### Details
+
+In most cases this hook is used to control the timing of the view switching, because the view switching will not happen until this hook is resolved.
+
+This hook is called top-down. A child view's `activate` will only get called when its parent view's `activate` has been resolved.

docs/pipeline/can-activate.md

@@ -0,0 +1,26 @@
+# `canActivate(transition) [-> Promise | Boolean]`
+
+Called on an incoming component during the validation phase.
+
+### Arguments
+
+- `transition`
+
+  Call `transition.next()` to resolve the hook. Calling `transition.abort()` will invalidate and cancel the transition.
+
+### Return Value
+
+- Optionally return a Promise:
+
+  - `resolve(true)` -> `transition.next()`
+  - `resolve(false)` -> `transition.abort()`
+  - `reject(reason)` -> `transition.abort(reason)`
+
+- Optionally return a Boolean:
+
+  - `true` -> `transition.next()`
+  - `false` -> `transition.abort()`
+
+### Details
+
+This hook is called top-down. A child view's `canActivate` will only get called when its parent view's `canActivate` has been resolved.

docs/pipeline/can-deactivate.md

@@ -0,0 +1,26 @@
+# `canDeactivate(transition) [-> Promise | Boolean]`
+
+Called on a leaving component during the validation phase.
+
+### Arguments
+
+- `transition`
+
+  Call `transition.next()` to resolve the hook. Calling `transition.abort()` will invalidate and cancel the transition.
+
+### Return Value
+
+- Optionally return a Promise:
+
+  - `resolve(true)` -> `transition.next()`
+  - `resolve(false)` -> `transition.abort()`
+  - `reject(reason)` -> `transition.abort(reason)`
+
+- Optionally return a Boolean:
+
+  - `true` -> `transition.next()`
+  - `false` -> `transition.abort()`
+
+### Details
+
+This hook is called from bottom-up. A parent view component's `canDeactivate` only gets called when its child's `canDeactivate` has resolved.

docs/pipeline/can-reuse.md

@@ -0,0 +1,21 @@
+# `canReuse {Boolean} | canReuse(transition) -> Boolean`
+
+Determines whether a component can be reused. If a component cannot be reused, the current instance will be replaced by a new one and it will go through the normal validation and activation phase.
+
+This route options can either be a plain Boolean value, or a function that synchronously returns a Boolean. **Defaults to `true`**.
+
+### Arguments
+
+- `transition`
+
+  You can only access `transition.to` and `transition.from` in a `canReuse` hook.
+
+### Return Value
+
+- Must return a Boolean. Falsy values are treated as `false`.
+
+### Details
+
+`canReuse` is called synchronously, top-down for all potentially reusable components.
+
+If a component is reused, its `data` hook will still get called during the activation phase.

docs/pipeline/data.md

@@ -1,5 +1,7 @@
 # `data(transition) [-> Promise]`
 
+Called on an incoming component during the activation phase, after the `activation` hook has been resolved. Load and set data on the current component.
+
 ### Arguments
 
 - `transition`
@@ -8,7 +10,9 @@
 
 ### Return Value
 
-- optionally return a Promise that resolves to the data to be set on the component.
+- optionally return a Promise.
+  - `resolve(data)` -> `transition.next(data)`
+  - `reject(reason)` -> `transition.abort(reason)`
 
 ### Details
 
@@ -28,6 +32,8 @@ The `data` hook is different from `activate` in that:
 
   - Instead, we can react to user input instantly and start switching the view, while displaying the new component with a "loading" state. If we have a CSS transition in between, the animation time can overlap nicely with the data wait time.
 
+With that said, if you still wish to wait until data is loaded before switching the view, you can add **`waitForData: true`** inside your component's `route` option.
+
 ### Examples
 
 By calling `transition.next`:

docs/pipeline/deactivate.md

@@ -0,0 +1,21 @@
+# `deactivate(transition) [-> Promise]`
+
+Called on a leaving component the activation phase when it is about to be deactivated and removed.
+
+### Arguments
+
+- `transition`
+
+  Call `transition.next()` to resolve the hook. Note calling `transition.abort()` here will not take the app back to the previous route because the transition has already been validated.
+
+### Return Value
+
+- Optionally return a Promise.
+  - `resolve` -> `transition.next()`
+  - `reject(reason)` -> `transition.abort(reason)`
+
+### Details
+
+This hook is called from bottom-up. A parent view component's `deactivate` only gets called when its child's `deactivate` has resolved.
+
+New components' `activate` hooks will only get called when all current components' `deactivate` hooks have been resolved.