refactor(router): renames PRIMARY_OUTLET into primary

modules/@angular/router/src/create_url_tree.ts

@@ -88,11 +88,10 @@ function normalizeCommands(commands: any[]): NormalizedNavigationCommands {
     if (typeof c === 'object' && c.outlets !== undefined) {
       const r: {[k: string]: any} = {};
       forEach(c.outlets, (commands: any, name: string) => {
-        const n = name === '' ? PRIMARY_OUTLET : name;
         if (typeof commands === 'string') {
-          r[n] = commands.split('/');
+          r[name] = commands.split('/');
         } else {
-          r[n] = commands;
+          r[name] = commands;
         }
       });
       res.push({outlets: r});

modules/@angular/router/src/directives/router_link.ts

@@ -60,6 +60,13 @@ import {UrlTree} from '../url_tree';
  component</a>
  * ```
  *
+ * The router link directive always treats it the provided input as a delta to the current url.
+ *
+ * For instance, if the current url is `/user/(box//aux:team)`.
+ *
+ * Then the following link `<a [routerLink]="['/user/jim']">Jim</a>` will generate the link
+ * `/user/(jim//aux:team)`. See {@link Router.createUrlTree} for more information.
+ *
  * @stable
  */
 @Directive({selector: ':not(a)[routerLink]'})

modules/@angular/router/src/router.ts

@@ -222,7 +222,10 @@ export class Router {
    * router.createUrlTree(['/team/33/user', userId]);
    *
    * // create /team/33/(user/11//aux:chat)
-   * router.createUrlTree(['/team', 33, {outlets: {"": 'user/11', right: 'chat'}}]);
+   * router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: 'chat'}}]);
+   *
+   * // remove the right secondary node
+   * router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: null}}]);
    *
    * // assuming the current url is `/team/33/user/11` and the route points to `user/11`
    *
@@ -258,6 +261,9 @@ export class Router {
    * ```
    * router.navigateByUrl("/team/33/user/11");
    * ```
+   *
+   * In opposite to `navigate`, `navigateByUrl` takes a whole URL
+   * and does not apply any delta to the current one.
    */
   navigateByUrl(url: string|UrlTree): Promise<boolean> {
     if (url instanceof UrlTree) {
@@ -282,6 +288,9 @@ export class Router {
    * ```
    * router.navigate(['team', 33, 'team', '11], {relativeTo: route});
    * ```
+   *
+   * In opposite to `navigateByUrl`, `navigate` always takes a detla
+   * that is applied to the current URL.
    */
   navigate(commands: any[], extras: NavigationExtras = {}): Promise<boolean> {
     return this.scheduleNavigation(this.createUrlTree(commands, extras), false);

modules/@angular/router/src/shared.ts

@@ -12,7 +12,7 @@
  *
  * @experimental
  */
-export const PRIMARY_OUTLET = 'PRIMARY_OUTLET';
+export const PRIMARY_OUTLET = 'primary';
 
 /**
  * A collection of parameters.

modules/@angular/router/test/create_url_tree.spec.ts

@@ -68,13 +68,13 @@ describe('createUrlTree', () => {
 
   it('should support updating primary and secondary segments at once', () => {
     const p = serializer.parse('/a(right:b)');
-    const t = createRoot(p, [{outlets: {'': 'y/z', right: 'c/11/d'}}]);
+    const t = createRoot(p, [{outlets: {primary: 'y/z', right: 'c/11/d'}}]);
     expect(serializer.serialize(t)).toEqual('/y/z(right:c/11/d)');
   });
 
   it('should support removing primary segment', () => {
     const p = serializer.parse('/a/(b//right:c)');
-    const t = createRoot(p, ['a', {outlets: {'': null, right: 'd'}}]);
+    const t = createRoot(p, ['a', {outlets: {primary: null, right: 'd'}}]);
     expect(serializer.serialize(t)).toEqual('/a/(right:d)');
   });