docs(router): adds some docs for ion-router

core/src/components.d.ts

@@ -2601,7 +2601,7 @@ declare global {
   namespace JSXElements {
     export interface IonRouteRedirectAttributes extends HTMLAttributes {
       from?: string;
-      to?: string;
+      to?: string|undefined;
     }
   }
 }

core/src/components/route-redirect/readme.md

@@ -1,6 +1,68 @@
-# ion-route
+# ion-route-redirect
+
+A redirect router can only be used in the scope of `ion-router` as a direct children of it.
+
+This route has only two configurable values:
+ - `from`
+ - `to`
+
+Their meaning is obvious under the context of a redirection, that ocurrs `from` a given URL `to` another given URL.
+
+In other for a redirection to occurs the `from` path needs to be an exact match of the navigated URL.
+
+## Redirection evaluation
+
+An arbitrary number of redirect routes can be defined inside an `ion-router`, but only one can match.
+
+Also, a redirection route WILL never redirect to another redirection router, since this could lead to infinity loops.
+
+Let's say we have this two redirection rules:
+
+```html
+<ion-router>
+  <ion-route-redirect from="/admin" to="/login"/>
+  <ion-route-redirect from="/login" to="/admin"/>
+</ion-router>
+```
+
+And the user navigates to `/admin`. The router will then redirect to `/login` and stop there.
+
+It WILL NOT never evalute more than one redirection rule in a roll.
 
 
+## Examples
+
+### Simple path
+
+```html
+<ion-route-redirect from="/admin" to="/login">
+```
+
+This route will apply (redirect) when the user navigates to: `/admin` but it will NOT apply if the user navigates to `/admin/posts`.
+
+In order to match any subpath of admin, the wildcard character (`*`) needs to be used.
+
+```html
+<ion-route-redirect from="/admin/*" to="/login">
+```
+
+### Redirect all routes to login
+
+Redirection routes can work as guards, since that can prevent user to navigate to areas to your application based in a given condition, for example, if the user is authenticated or not.
+
+
+```tsx
+{!this.isLoggedIn &&
+  <ion-route-redirect from="*" to="/login"/> }
+```
+
+A router can be added and removed dynamically to redirect (or guard) some routes from being accessed.
+
+Another approach is to modify the value of `to`, since given `to` the value of `null` or `undefined` makes disables the redirection.
+
+```tsx
+ <ion-route-redirect from="*" to={this.isLoggedin ? undefined : '/login'}/>
+```
 
 <!-- Auto Generated Below -->
 
@@ -11,10 +73,29 @@
 
 string
 
+A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
+It needs to be an exact match of the navigated URL in order to apply.
+
+The path specified in this value is always an absolute path, even if the initial `/` slash
+is not specified.
+
 
 #### to
 
-string
+
+
+A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
+When the defined `ion-route-redirect` rule matches, the router will redirect to the path
+specified in this property.
+
+The value of this property is always an absolute path inside the scope of routes defined in
+`ion-router` it can't be used with another router or to perfom a redirection to a different domain.
+
+Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
+a redirect inside the context of ion-router.
+
+When this property is not specified or his value is `undefined` the whole redirect route is noop,
+even if the "from" value matches.
 
 
 ## Attributes
@@ -23,16 +104,40 @@ string
 
 string
 
+A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
+It needs to be an exact match of the navigated URL in order to apply.
+
+The path specified in this value is always an absolute path, even if the initial `/` slash
+is not specified.
+
 
 #### to
 
-string
+
+
+A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
+When the defined `ion-route-redirect` rule matches, the router will redirect to the path
+specified in this property.
+
+The value of this property is always an absolute path inside the scope of routes defined in
+`ion-router` it can't be used with another router or to perfom a redirection to a different domain.
+
+Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
+a redirect inside the context of ion-router.
+
+When this property is not specified or his value is `undefined` the whole redirect route is noop,
+even if the "from" value matches.
 
 
 ## Events
 
 #### ionRouteRedirectChanged
 
+Internal event that fires when any value of this rule is added/removed from the DOM,
+or any of his public properties changes.
+
+`ion-router` captures this event in order to update his internal registry of router rules.
+
 
 
 ----------------------------------------------

core/src/components/route-redirect/route-redirect.tsx

@@ -6,9 +6,38 @@ import { EventEmitter } from 'ionicons/dist/types/stencil.core';
 })
 export class RouteRedirect {
 
+  /**
+   * A redirect route, redirects "from" a URL "to" another URL. This property is that "from" URL.
+   * It needs to be an exact match of the navigated URL in order to apply.
+   *
+   * The path specified in this value is always an absolute path, even if the initial `/` slash
+   * is not specified.
+   *
+   */
   @Prop() from = '';
-  @Prop() to: string;
 
+  /**
+   * A redirect route, redirects "from" a URL "to" another URL. This property is that "to" URL.
+   * When the defined `ion-route-redirect` rule matches, the router will redirect to the path
+   * specified in this property.
+   *
+   * The value of this property is always an absolute path inside the scope of routes defined in
+   * `ion-router` it can't be used with another router or to perfom a redirection to a different domain.
+   *
+   * Note that this is a virtual redirect, it will not cause a real browser refresh, again, it's
+   * a redirect inside the context of ion-router.
+   *
+   * When this property is not specified or his value is `undefined` the whole redirect route is noop,
+   * even if the "from" value matches.
+   */
+  @Prop() to: string|undefined;
+
+  /**
+   * Internal event that fires when any value of this rule is added/removed from the DOM,
+   * or any of his public properties changes.
+   *
+   * `ion-router` captures this event in order to update his internal registry of router rules.
+   */
   @Event() ionRouteRedirectChanged: EventEmitter;
 
   componentDidLoad() {

core/src/components/route/readme.md

@@ -11,16 +11,26 @@
 
 string
 
+Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
+when the route matches.
+
+The value of this property is not always the tagname of the component to load,
+in ion-tabs it actually refers to the name of the `ion-tab` to select.
+
 
 #### componentProps
 
 
 
+Props to pass when the `component` specified in this route load.
+
 
 #### url
 
 string
 
+Relative path that needs to match in order for this route to apply.
+
 
 ## Attributes
 
@@ -28,21 +38,33 @@ string
 
 string
 
+Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
+when the route matches.
+
+The value of this property is not always the tagname of the component to load,
+in ion-tabs it actually refers to the name of the `ion-tab` to select.
+
 
 #### component-props
 
 
 
+Props to pass when the `component` specified in this route load.
+
 
 #### url
 
 string
 
+Relative path that needs to match in order for this route to apply.
+
 
 ## Events
 
 #### ionRouteDataChanged
 
+Used internaly by `ion-router` to know when this route did change.
+
 
 
 ----------------------------------------------

core/src/components/route/route.tsx

@@ -6,10 +6,28 @@ import { EventEmitter } from 'ionicons/dist/types/stencil.core';
 })
 export class Route {
 
+  /**
+   * Relative path that needs to match in order for this route to apply.
+   */
   @Prop() url = '';
+
+  /**
+   * Name of the component to load/select in the navigation outlet (`ion-tabs`, `ion-nav`)
+   * when the route matches.
+   *
+   * The value of this property is not always the tagname of the component to load,
+   * in ion-tabs it actually refers to the name of the `ion-tab` to select.
+   */
   @Prop() component: string;
+
+  /**
+   * Props to pass when the `component` specified in this route load.
+   */
   @Prop() componentProps: {[key: string]: any};
 
+  /**
+   * Used internaly by `ion-router` to know when this route did change.
+   */
   @Event() ionRouteDataChanged: EventEmitter;
 
   componentDidLoad() {

core/src/components/router/readme.md

@@ -1,4 +1,48 @@
-# ion-router-controller
+# ion-router
+
+`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-nav` and `ion-tabs`.
+
+That means the ion-router never touches the DOM, it does NOT show the components or emit any kind of lifecycle event, it just tell `ion-nav` and `ion-tabs` what to "show" based in the browser's URL.
+
+In order to configure this relationship between components (to load/select) and URLs, ion-router uses a declarative syntax using JSX/HTML to define a tree of routes.
+
+## Tree of routes
+
+The way to structure navigation in an ionic app is by nesting `ion-nav`s and `ion-tabs`, for example, you have an `ion-nav` at the root, where you "push" an page that has an `ion-tabs`, then inside each tab (`ion-tab`) you might have another `ion-nav` since you want navigation independent navigation for each tab.
+
+Obviously this structure is app-dependent, but in any case, nesting router-outlets (ion-nav or ion-tabs) is a common pattern. This is way the routes defined in `ion-router` are not a list of routes, but an tree.
+
+Any route can have a list of nested routes:
+
+```
+<ion-router>
+  <ion-route component="page-tabs">
+    <ion-route url="/schedule" component="tab-schedule">
+      <ion-route component="page-schedule"></ion-route>
+      <ion-route url="/session/:sessionId" component="page-session"></ion-route>
+    </ion-route>
+
+    <ion-route url="/speakers" component="tab-speaker">
+      <ion-route component="page-speaker-list"></ion-route>
+      <ion-route url="/session/:sessionId" component="page-session"></ion-route>
+      <ion-route url="/:speakerId" component="page-speaker-detail"></ion-route>
+    </ion-route>
+
+    <ion-route url="/map" component="page-map"></ion-route>
+    <ion-route url="/about" component="page-about"></ion-route>
+  </ion-route>
+
+  <ion-route url="/tutorial" component="page-tutorial"></ion-route>
+  <ion-route url="/login" component="page-login"></ion-route>
+  <ion-route url="/account" component="page-account"></ion-route>
+  <ion-route url="/signup" component="page-signup"></ion-route>
+  <ion-route url="/support" component="page-support"></ion-route>
+</ion-router>
+
+```
+
+This hierarchy of routes matches the hierarchy of how `ion-tab`s and `ion-nav`s are nested together.
+