docs: scroll position improvements for navigation (#11671)

cache current scroll position to restore when user goes back to a previouly visited route.
explicitly scroll to top when route change is due to menu-link interaction.

Fixes #11669

Author: gaurav5430

docs/app/js/app.js

@@ -491,7 +491,7 @@ function(SERVICES, COMPONENTS, DEMOS, PAGES, $location, $rootScope, $http, $wind
   }
 }])
 
-.directive('menuLink', function() {
+.directive('menuLink', ['scrollCache', function(scrollCache) {
   return {
     scope: {
       section: '='
@@ -508,10 +508,12 @@ function(SERVICES, COMPONENTS, DEMOS, PAGES, $location, $rootScope, $http, $wind
         // set flag to be used later when
         // $locationChangeSuccess calls openPage()
         controller.autoFocusContent = true;
+        // set flag to be used later when $routeChangeStart saves scroll position
+        scrollCache.linkClicked = true;
       };
     }
   };
-})
+}])
 
 .directive('menuToggle', ['$mdUtil', '$animateCss', '$$rAF', function($mdUtil, $animateCss, $$rAF) {
   return {
@@ -881,4 +883,78 @@ function($rootScope, $scope, component, demos, $templateRequest) {
       }
     }
   };
-});
+})
+
+.factory('scrollCache', function() {
+  var cache = {};
+  var linkClicked = false;
+
+  function setScroll(key, scrollPostion) {
+    cache[key] = scrollPostion;
+  }
+
+  function getScroll(key) {
+    return cache[key] || 0;
+  }
+
+  return {
+    getScroll: getScroll,
+    setScroll: setScroll,
+    linkClicked: linkClicked
+  };
+})
+
+/**
+ * This directive caches the scroll position for each route + templateUrl combination.
+ * This helps in restoring the scroll when the user uses back or forward navigation to return
+ * to a page.
+ */
+.directive('cacheScrollPosition', ['$route', '$mdUtil', '$timeout', '$location', '$anchorScroll',
+  'scrollCache',
+function($route, $mdUtil, $timeout, $location, $anchorScroll, scrollCache) {
+  var mainContentArea = document.querySelector("[role='main']");
+  var scrollContentEl = mainContentArea.querySelector('md-content[md-scroll-y]');
+
+  /**
+   * @param {Object} event Synthetic event object
+   * @param {Object} next Future route information
+   * @param {Object} current Current route information
+   */
+  var handleRouteChangeStart = function (event, next, current) {
+    // store scroll position for the current path + template
+    if ($route.current) {
+      scrollCache.setScroll(current.loadedTemplateUrl + ":" + current.$$route.originalPath,
+        scrollContentEl.scrollTop);
+    }
+
+    // set scroll to 0 for next route, if explicitly clicked on link.
+    if (scrollCache.linkClicked) {
+      scrollCache.setScroll(next.$$route.templateUrl + ":" + next.$$route.originalPath, 0);
+      scrollCache.linkClicked = false;
+    }
+  };
+
+  /**
+   * @param {Object} event Synthetic event object
+   * @param {Object} current Current route information
+   */
+  var handleRouteChangeSuccess = function (event, current) {
+    // if hash is specified explicitly, it trumps previously stored scroll position
+    if ($location.hash()) {
+      $anchorScroll();
+    } else {
+      // Get previous scroll position; if none, scroll to the top of the page
+      var prevScrollPos = scrollCache.getScroll(current.loadedTemplateUrl + ":" +
+        current.$$route.originalPath);
+
+      $timeout(function() {
+        $mdUtil.animateScrollTo(scrollContentEl, prevScrollPos);
+      }, 0);
+    }
+  };
+
+  return function(scope) {
+    scope.$on('$routeChangeStart', handleRouteChangeStart);
+    scope.$on('$routeChangeSuccess', handleRouteChangeSuccess);
+  }
+}]);

docs/config/template/index.template.html

@@ -155,7 +155,7 @@ <h2 class="md-toolbar-item md-breadcrumb md-headline">
     </md-toolbar>
 
     <md-content md-scroll-y layout="column" flex>
-      <div ng-view layout-padding flex="noshrink" class="docs-ng-view"></div>
+      <div ng-view layout-padding flex="noshrink" class="docs-ng-view" cache-scroll-position></div>
 
       <div layout="row" flex="noshrink" layout-align="center center">
         <div id="license-footer" flex>