feat(common): add @angular/common/upgrade package for $location-related APIs (#30055)

AngularJS's `$location` service doesn't have a direct counterpart in Angular. This is largely because the `Location` service in Angular was pulled out of the `Router`, but was not purpose-built to stand on its own.

This commit adds a new `@angular/common/upgrade` package with the beginnings of a new `LocationUpgradeService`. This service will more closely match the API of AngularJS and provide a way to replace the `$location` service from AngularJS.

PR Close #30055

packages/common/src/location/platform_location.ts

@@ -35,6 +35,7 @@ export abstract class PlatformLocation {
   abstract onPopState(fn: LocationChangeListener): void;
   abstract onHashChange(fn: LocationChangeListener): void;
 
+  abstract get href(): string;
   abstract get protocol(): string;
   abstract get hostname(): string;
   abstract get port(): string;

packages/common/upgrade/BUILD.bazel

@@ -0,0 +1,20 @@
+package(default_visibility = ["//visibility:public"])
+
+exports_files(["package.json"])
+
+load("//tools:defaults.bzl", "ng_module")
+
+ng_module(
+    name = "upgrade",
+    srcs = glob(
+        [
+            "*.ts",
+            "src/**/*.ts",
+        ],
+    ),
+    deps = [
+        "//packages/common",
+        "//packages/core",
+        "//packages/upgrade/static",
+    ],
+)

packages/common/upgrade/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// This file is not used to build this module. It is only used during editing
+// by the TypeScript language service and during build for verification. `ngc`
+// replaces this file with production index.ts when it rewrites private symbol
+// names.
+
+export * from './public_api';

packages/common/upgrade/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@angular/common/upgrade",
+  "typings": "./upgrade.d.ts",
+  "main": "../bundles/common-upgrade.umd.js",
+  "module": "../fesm5/upgrade.js",
+  "es2015": "../fesm2015/upgrade.js",
+  "esm5": "../esm5/upgrade/upgrade.js",
+  "esm2015": "../esm2015/upgrade/upgrade.js",
+  "fesm5": "../fesm5/upgrade.js",
+  "fesm2015": "../fesm2015/upgrade.js",
+  "sideEffects": false
+}

packages/common/upgrade/public_api.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+/**
+ * @module
+ * @description
+ * Entry point for all public APIs of this package.
+ */
+export * from './src/index';
+
+// This file only reexports content of the `src` folder. Keep it that way.

packages/common/upgrade/rollup.config.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+const resolve = require('rollup-plugin-node-resolve');
+const sourcemaps = require('rollup-plugin-sourcemaps');
+
+const globals = {
+  '@angular/core': 'ng.core',
+  '@angular/common': 'ng.common',
+  '@angular/upgrade/static': 'ng.upgrade.static'
+};
+
+
+module.exports = {
+  entry: '../../../dist/packages-dist/common/fesm5/upgrade.js',
+  dest: '../../../dist/packages-dist/common/bundles/common-upgrade.umd.js',
+  format: 'umd',
+  exports: 'named',
+  amd: {id: '@angular/common/upgrade'},
+  moduleName: 'ng.common.upgrade',
+  plugins: [resolve(), sourcemaps()],
+  external: Object.keys(globals),
+  globals: globals
+};

packages/common/upgrade/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export * from './location';
+export * from './location_module';

packages/common/upgrade/src/location.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Injectable} from '@angular/core';
+
+/**
+ * A Location service that provides properties and methods to match AngularJS's `$location`
+ * service. It is recommended that this LocationUpgradeService be used in place of
+ * `$location` in any hybrid Angular/AngularJS applications.
+ */
+@Injectable()
+export class LocationUpgradeService {
+}

packages/common/upgrade/src/location_module.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {NgModule} from '@angular/core';
+import {LocationUpgradeService} from './location';
+
+/**
+ * Module used for configuring Angular's LocationUpgradeService.
+ */
+@NgModule({providers: [LocationUpgradeService]})
+export class LocationUpgradeModule {
+}

packages/common/upgrade/test/BUILD.bazel

@@ -0,0 +1,23 @@
+load("//tools:defaults.bzl", "jasmine_node_test", "ts_library", "ts_web_test_suite")
+
+ts_library(
+    name = "test_lib",
+    testonly = True,
+    srcs = glob(["**/*.ts"]),
+    deps = [
+        "//packages/common",
+        "//packages/common/upgrade",
+        "//packages/common/testing",
+        "//packages/core/testing",
+        "//packages/upgrade/static",
+    ],
+)
+
+jasmine_node_test(
+    name = "test",
+    bootstrap = ["angular/tools/testing/init_node_spec.js"],
+    deps = [
+        ":test_lib",
+        "//tools/testing:node",
+    ],
+)

packages/common/upgrade/test/upgrade.spec.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {LocationUpgradeModule, LocationUpgradeService} from '@angular/common/upgrade';
+import {TestBed, inject} from '@angular/core/testing';
+import {UpgradeModule} from '@angular/upgrade/static';
+
+describe('LocationUpgradeService', () => {
+  let upgradeModule: UpgradeModule;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [LocationUpgradeModule],
+      providers: [UpgradeModule],
+    });
+
+    upgradeModule = TestBed.get(UpgradeModule);
+    upgradeModule.$injector = {
+      get: jasmine.createSpy('$injector.get').and.returnValue({'$on': () => undefined})
+    };
+  });
+
+  it('should instantiate LocationUpgradeService',
+     inject([LocationUpgradeService], (location: LocationUpgradeService) => {
+       expect(location).toBeDefined();
+       expect(location instanceof LocationUpgradeService).toBe(true);
+     }));
+});

packages/common/upgrade/tsconfig-build.json

@@ -0,0 +1,32 @@
+{
+  "extends": "../tsconfig-build.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "../",
+    "paths": {
+      "@angular/common": [
+        "../../../dist/packages/common"
+      ],
+      "@angular/core": [
+        "../../../dist/packages/core"
+      ],
+      "@angular/platform-browser": [
+        "../../../dist/packages/platform-browser"
+      ],
+      "@angular/upgrade/static": [
+        "../../../dist/packages/upgrade/static"
+      ]
+    },
+    "outDir": "../../../dist/packages/common"
+  },
+  "files": [
+    "public_api.ts"
+  ],
+  "angularCompilerOptions": {
+    "annotateForClosureCompiler": true,
+    "strictMetadataEmit": false,
+    "skipTemplateCodegen": true,
+    "flatModuleOutFile": "upgrade.js",
+    "flatModuleId": "@angular/common/upgrade"
+  }
+}

packages/platform-browser/src/browser/location/browser_platform_location.ts

@@ -49,6 +49,7 @@ export class BrowserPlatformLocation extends PlatformLocation {
     getDOM().getGlobalEventTarget(this._doc, 'window').addEventListener('hashchange', fn, false);
   }
 
+  get href(): string { return this.location.href; }
   get protocol(): string { return this.location.protocol; }
   get hostname(): string { return this.location.hostname; }
   get port(): string { return this.location.port; }

packages/platform-server/src/location.ts

@@ -32,6 +32,7 @@ function parseUrl(urlStr: string) {
  */
 @Injectable()
 export class ServerPlatformLocation implements PlatformLocation {
+  public readonly href: string = '/';
   public readonly hostname: string = '/';
   public readonly protocol: string = '/';
   public readonly port: string = '/';

packages/platform-webworker/src/web_workers/worker/platform_location.ts

@@ -74,6 +74,8 @@ export class WebWorkerPlatformLocation extends PlatformLocation {
 
   onHashChange(fn: LocationChangeListener): void { this._hashChangeListeners.push(fn); }
 
+  get href(): string { return this._location ? this._location.href ! : '<unknown>'; }
+
   get hostname(): string { return this._location ? this._location.host ! : '<unknown>'; }
 
   get port(): string { return this._location ? this._location.port ! : '<unknown>'; }