docs(router): some docs

core/src/components.d.ts

@@ -4984,7 +4984,7 @@ declare global {
       /**
        * 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.
        */
-      'to': string|undefined;
+      'to': string;
     }
   }
 
@@ -5018,7 +5018,7 @@ declare global {
       /**
        * 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.
        */
-      'to'?: string|undefined;
+      'to'?: string;
     }
   }
 }
@@ -5033,11 +5033,11 @@ declare global {
        */
       'component': string;
       /**
-       * Props to pass when the `component` specified in this route load.
+       * A key value `{ 'red': true, 'blue': 'white'}` containing props that should be passed to the defined component when rendered.
        */
       'componentProps': {[key: string]: any};
       /**
-       * Relative path that needs to match in order for this route to apply.
+       * Relative path that needs to match in order for this route to apply.  Accepts paths similar to expressjs so that you can define parameters in the url /foo/:bar where bar would be available in incoming props.
        */
       'url': string;
     }
@@ -5067,7 +5067,7 @@ declare global {
        */
       'component'?: string;
       /**
-       * Props to pass when the `component` specified in this route load.
+       * A key value `{ 'red': true, 'blue': 'white'}` containing props that should be passed to the defined component when rendered.
        */
       'componentProps'?: {[key: string]: any};
       /**
@@ -5075,7 +5075,7 @@ declare global {
        */
       'onIonRouteDataChanged'?: (event: CustomEvent<any>) => void;
       /**
-       * Relative path that needs to match in order for this route to apply.
+       * Relative path that needs to match in order for this route to apply.  Accepts paths similar to expressjs so that you can define parameters in the url /foo/:bar where bar would be available in incoming props.
        */
       'url'?: string;
     }
@@ -5130,9 +5130,15 @@ declare global {
 
   namespace StencilComponents {
     interface IonRouter {
-      'base': string;
       'navChanged': (direction: RouterDirection) => Promise<boolean>;
       'push': (url: string, direction?: RouterDirection) => Promise<boolean>;
+      /**
+       * By default `ion-router` will match the routes at the root path ("/"). That can be changed when  T
+       */
+      'root': string;
+      /**
+       * The router can work in two "modes": - With hash: `/index.html#/path/to/page` - Without hash: `/path/to/page`  Using one or another might depend in the requirements of your app and/or where it's deployed.  Usually "hash-less" navigation works better for SEO and it's more user friendly too, but it might requires aditional server-side configuration in order to properly work.  On the otherside hash-navigation is much easier to deploy, it even works over the file protocol.  By default, this property is `true`, change to `false` to allow hash-less URLs.
+       */
       'useHash': boolean;
     }
   }
@@ -5156,8 +5162,14 @@ declare global {
   }
   namespace JSXElements {
     export interface IonRouterAttributes extends HTMLAttributes {
-      'base'?: string;
       'onIonRouteChanged'?: (event: CustomEvent<RouterEventDetail>) => void;
+      /**
+       * By default `ion-router` will match the routes at the root path ("/"). That can be changed when  T
+       */
+      'root'?: string;
+      /**
+       * The router can work in two "modes": - With hash: `/index.html#/path/to/page` - Without hash: `/path/to/page`  Using one or another might depend in the requirements of your app and/or where it's deployed.  Usually "hash-less" navigation works better for SEO and it's more user friendly too, but it might requires aditional server-side configuration in order to properly work.  On the otherside hash-navigation is much easier to deploy, it even works over the file protocol.  By default, this property is `true`, change to `false` to allow hash-less URLs.
+       */
       'useHash'?: boolean;
     }
   }

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

@@ -30,7 +30,7 @@ export class RouteRedirect {
    * 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;
+  @Prop() to?: string;
 
   /**
    * Internal event that fires when any value of this rule is added/removed from the DOM,

core/src/components/route/readme.md

@@ -22,7 +22,8 @@ in ion-tabs it actually refers to the name of the `ion-tab` to select.
 
 
 
-Props to pass when the `component` specified in this route load.
+A key value `{ 'red': true, 'blue': 'white'}` containing props that should be passed
+to the defined component when rendered.
 
 
 #### url
@@ -31,6 +32,9 @@ string
 
 Relative path that needs to match in order for this route to apply.
 
+Accepts paths similar to expressjs so that you can define parameters
+in the url /foo/:bar where bar would be available in incoming props.
+
 
 ## Attributes
 
@@ -49,7 +53,8 @@ in ion-tabs it actually refers to the name of the `ion-tab` to select.
 
 
 
-Props to pass when the `component` specified in this route load.
+A key value `{ 'red': true, 'blue': 'white'}` containing props that should be passed
+to the defined component when rendered.
 
 
 #### url
@@ -58,6 +63,9 @@ string
 
 Relative path that needs to match in order for this route to apply.
 
+Accepts paths similar to expressjs so that you can define parameters
+in the url /foo/:bar where bar would be available in incoming props.
+
 
 ## Events
 

core/src/components/route/route.tsx

@@ -8,6 +8,9 @@ export class Route {
 
   /**
    * Relative path that needs to match in order for this route to apply.
+   *
+   * Accepts paths similar to expressjs so that you can define parameters
+   * in the url /foo/:bar where bar would be available in incoming props.
    */
   @Prop() url = '';
 
@@ -21,7 +24,8 @@ export class Route {
   @Prop() component!: string;
 
   /**
-   * Props to pass when the `component` specified in this route load.
+   * A key value `{ 'red': true, 'blue': 'white'}` containing props that should be passed
+   * to the defined component when rendered.
    */
   @Prop() componentProps?: {[key: string]: any};
 

core/src/components/router/readme.md

@@ -1,20 +1,38 @@
 # ion-router
 
+You should have one single `ion-router` component in your project. This component controls all interactions with the browser history and it aggregates updates through an event system.
+
 `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.
+That means the ion-router never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tell `ion-nav` and `ion-tabs` what and when 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.
 
+
+## Ecosystem of components
+
+### Configuration
+
+- <ion-router>
+- <ion-route>
+- <ion-router-redirect>
+
+### Outlets
+
+- <ion-nav>
+- <ion-router-outlet>
+- <ion-tab>
+
+
 ## 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.
+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 might want 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.
+Obviously this structure is app-dependent, but in any case, nesting router-outlets (ion-nav or ion-tabs) is a common pattern. This is why the routes defined in `ion-router` are not a list of routes, but an tree.
 
 Any route can have a list of nested routes:
 
-```
+```html
 <ion-router>
   <ion-route component="page-tabs">
     <ion-route url="/schedule" component="tab-schedule">
@@ -43,7 +61,17 @@ Any route can have a list of nested routes:
 
 This hierarchy of routes matches the hierarchy of how `ion-tab`s and `ion-nav`s are nested together.
 
+## Router configuration
 
+## Router guards and redirections
+
+## Navigating Statically
+
+## Navigating Dynamically
+
+## URL params and data passing
+
+## JSX reactiviness
 
 
 <!-- Auto Generated Below -->
@@ -51,27 +79,63 @@ This hierarchy of routes matches the hierarchy of how `ion-tab`s and `ion-nav`s
 
 ## Properties
 
-#### base
+#### root
 
 string
 
+By default `ion-router` will match the routes at the root path ("/").
+That can be changed when
+
+T
+
 
 #### useHash
 
 boolean
 
+The router can work in two "modes":
+- With hash: `/index.html#/path/to/page`
+- Without hash: `/path/to/page`
+
+Using one or another might depend in the requirements of your app and/or where it's deployed.
+
+Usually "hash-less" navigation works better for SEO and it's more user friendly too, but it might
+requires aditional server-side configuration in order to properly work.
+
+On the otherside hash-navigation is much easier to deploy, it even works over the file protocol.
+
+By default, this property is `true`, change to `false` to allow hash-less URLs.
+
 
 ## Attributes
 
-#### base
+#### root
 
 string
 
+By default `ion-router` will match the routes at the root path ("/").
+That can be changed when
+
+T
+
 
 #### use-hash
 
 boolean
 
+The router can work in two "modes":
+- With hash: `/index.html#/path/to/page`
+- Without hash: `/path/to/page`
+
+Using one or another might depend in the requirements of your app and/or where it's deployed.
+
+Usually "hash-less" navigation works better for SEO and it's more user friendly too, but it might
+requires aditional server-side configuration in order to properly work.
+
+On the otherside hash-navigation is much easier to deploy, it even works over the file protocol.
+
+By default, this property is `true`, change to `false` to allow hash-less URLs.
+
 
 ## Events
 

core/src/components/router/router.tsx

@@ -27,7 +27,28 @@ export class Router {
   @Prop({ context: 'window' }) win!: Window;
   @Prop({ context: 'isServer' }) isServer!: boolean;
 
-  @Prop() base = '';
+  /**
+   * By default `ion-router` will match the routes at the root path ("/").
+   * That can be changed when
+   *
+   * T
+   */
+  @Prop() root = '/';
+
+  /**
+   * The router can work in two "modes":
+   * - With hash: `/index.html#/path/to/page`
+   * - Without hash: `/path/to/page`
+   *
+   * Using one or another might depend in the requirements of your app and/or where it's deployed.
+   *
+   * Usually "hash-less" navigation works better for SEO and it's more user friendly too, but it might
+   * requires aditional server-side configuration in order to properly work.
+   *
+   * On the otherside hash-navigation is much easier to deploy, it even works over the file protocol.
+   *
+   * By default, this property is `true`, change to `false` to allow hash-less URLs.
+   */
   @Prop() useHash = true;
 
   @Event() ionRouteChanged!: EventEmitter<RouterEventDetail>;
@@ -187,11 +208,11 @@ export class Router {
 
   private setPath(path: string[], direction: RouterDirection) {
     this.state++;
-    writePath(this.win.history, this.base, this.useHash, path, direction, this.state);
+    writePath(this.win.history, this.root, this.useHash, path, direction, this.state);
   }
 
   private getPath(): string[] | null {
-    return readPath(this.win.location, this.base, this.useHash);
+    return readPath(this.win.location, this.root, this.useHash);
   }
 
   private emitRouteChange(path: string[], redirectPath: string[]|null) {