feat($anchorScroll): add support for scrolling independently of $location.hash()

Add an optional argument to `$anchorScroll()` to enable scrolling to an
anchor element different than that related to the current value of
`$location.hash()`. If the argument is omitted, the value of
`$location.hash()` will be used instead.

Closes angular#4568

Author: gkalpak

src/ng/anchorScroll.js

@@ -50,8 +50,8 @@ function $AnchorScrollProvider() {
    * Additionally, you can use its {@link ng.$anchorScroll#yOffset yOffset} property to specify a
    * vertical scroll-offset (either fixed or dynamic).
    *
-   * @param {string} hash The hash specifying the element to scroll to. If omitted,
-   *                      {@link ng.$location#hash $location.hash()} will be used.
+   * @param {string=} hash The hash specifying the element to scroll to. If omitted, the value of
+   *                       {@link ng.$location#hash $location.hash()} will be used.
    *
    * @property {(number|function|jqLite)} yOffset
    * If set, specifies a vertical scroll-offset. This is often useful when there are fixed

test/ng/anchorScrollSpec.js

@@ -23,7 +23,6 @@ describe('$anchorScroll', function() {
     };
   }
 
-
   function addElements() {
     var elements = sliceArgs(arguments);
 
@@ -137,12 +136,12 @@ describe('$anchorScroll', function() {
   }));
 
 
-  describe('when implicitly using `$location.hash()`', function() {
+  describe('when explicitly called', function() {
 
     beforeEach(createMockWindow());
 
 
-    describe('and no hash is specified', function() {
+    describe('and implicitly using `$location.hash()`', function() {
 
       it('should scroll to top of the window if empty hash', inject(
         changeHashAndScroll(''),
@@ -189,6 +188,73 @@ describe('$anchorScroll', function() {
         changeHashAndScroll('top'),
         expectScrollingTo('id=top')));
     });
+
+
+    describe('and specifying a hash', function() {
+
+      it('should ignore the `hash` argument if not a string', inject(
+        spyOnJQLiteDocumentLoaded(),
+        addElements('id=one', 'id=two'),
+        changeHashTo('one'),   // won't scroll since `jqLiteDocumentLoaded()` is spied upon
+        callAnchorScroll({}),
+        expectScrollingTo('id=one'),
+        unspyOnJQLiteDocumentLoaded()));
+
+
+      it('should ignore `$location.hash()` if `hash` is passed as argument', inject(
+        spyOnJQLiteDocumentLoaded(),
+        addElements('id=one', 'id=two'),
+        changeHashTo('one'),   // won't scroll since `jqLiteDocumentLoaded()` is spied upon
+        callAnchorScroll('two'),
+        expectScrollingTo('id=two'),
+        unspyOnJQLiteDocumentLoaded()));
+
+
+      it('should scroll to top of the window if empty hash', inject(
+        callAnchorScroll(''),
+        expectScrollingToTop));
+
+
+      it('should not scroll if hash does not match any element', inject(
+        addElements('id=one', 'id=two'),
+        callAnchorScroll('non-existing'),
+        expectNoScrolling()));
+
+
+      it('should scroll to anchor element with name', inject(
+        addElements('a name=abc'),
+        callAnchorScroll('abc'),
+        expectScrollingTo('a name=abc')));
+
+
+      it('should not scroll to other than anchor element with name', inject(
+        addElements('input name=xxl', 'select name=xxl', 'form name=xxl'),
+        callAnchorScroll('xxl'),
+        expectNoScrolling()));
+
+
+      it('should scroll to anchor even if other element with given name exist', inject(
+        addElements('input name=some', 'a name=some'),
+        callAnchorScroll('some'),
+        expectScrollingTo('a name=some')));
+
+
+      it('should scroll to element with id with precedence over name', inject(
+        addElements('name=abc', 'id=abc'),
+        callAnchorScroll('abc'),
+        expectScrollingTo('id=abc')));
+
+
+      it('should scroll to top if hash == "top" and no matching element', inject(
+        callAnchorScroll('top'),
+        expectScrollingToTop));
+
+
+      it('should scroll to element with id "top" if present', inject(
+        addElements('id=top'),
+        callAnchorScroll('top'),
+        expectScrollingTo('id=top')));
+    });
   });