docs(): add jump to top fab button (#9786)

* Adds a Jump to Top Fab button at the right bottom of the docs page.
* The FAB button automatically shows when the content is scrolling (this runs outside of Angular to not trigger a digest per each scroll event)

Author: devversion

docs/app/css/style.css

@@ -33,6 +33,22 @@ body.docs-body {
   color: inherit;
 }
 
+.md-fab.docs-scroll-fab {
+  position: fixed !important;
+
+  transform: scale(0);
+
+  /* Manually prefix because the docs won't be prefixed. See #9785 */
+  -webkit-transition: transform 0.2s;
+  -moz-transition: transform 0.2s;
+  -o-transition: transform 0.2s;
+  transition: transform 0.2s;
+}
+
+.docs-scroll-fab.scrolling {
+  transform: scale(1);
+}
+
 #license-footer {
   align-self: flex-end;
   padding: 16px 32px;

docs/app/img/icons/ic_arrow_up_24px.svg

@@ -575,7 +575,8 @@ function(SERVICES, COMPONENTS, DEMOS, PAGES, $location, $rootScope, $http, $wind
   'menu',
   '$location',
   '$rootScope',
-function($scope, COMPONENTS, BUILDCONFIG, $mdSidenav, $timeout, $mdDialog, menu, $location, $rootScope) {
+  '$mdUtil',
+function($scope, COMPONENTS, BUILDCONFIG, $mdSidenav, $timeout, $mdDialog, menu, $location, $rootScope, $mdUtil) {
   var self = this;
 
   $scope.COMPONENTS = COMPONENTS;
@@ -587,6 +588,7 @@ function($scope, COMPONENTS, BUILDCONFIG, $mdSidenav, $timeout, $mdDialog, menu,
   $scope.openMenu = openMenu;
   $scope.closeMenu = closeMenu;
   $scope.isSectionSelected = isSectionSelected;
+  $scope.scrollTop = scrollTop;
 
   // Grab the current year so we don't have to update the license every year
   $scope.thisYear = (new Date()).getFullYear();
@@ -615,6 +617,8 @@ function($scope, COMPONENTS, BUILDCONFIG, $mdSidenav, $timeout, $mdDialog, menu,
 
 
   var mainContentArea = document.querySelector("[role='main']");
+  var scrollContentEl = mainContentArea.querySelector('md-content[md-scroll-y]');
+
 
   // *********************
   // Internal methods
@@ -632,6 +636,10 @@ function($scope, COMPONENTS, BUILDCONFIG, $mdSidenav, $timeout, $mdDialog, menu,
     return $location.path();
   }
 
+  function scrollTop() {
+    $mdUtil.animateScrollTo(scrollContentEl, 0, 200);
+  }
+
   function goHome($event) {
     menu.selectPage(null, null);
     $location.path( '/' );
@@ -826,4 +834,32 @@ function($rootScope, $scope, component, demos, $templateRequest) {
     // Just return the original string if we don't know what to do with it
     return str;
   };
+})
+
+/** Directive which applies a specified class to the element when being scrolled */
+.directive('docsScrollClass', function() {
+  return {
+    restrict: 'A',
+    link: function(scope, element, attr) {
+
+      var scrollParent = element.parent();
+      var isScrolling = false;
+
+      // Initial update of the state.
+      updateState();
+
+      // Register a scroll listener, which updates the state.
+      scrollParent.on('scroll', updateState);
+
+      function updateState() {
+        var newState = scrollParent[0].scrollTop !== 0;
+
+        if (newState !== isScrolling) {
+          element.toggleClass(attr.docsScrollClass, newState);
+        }
+
+        isScrolling = newState;
+      }
+    }
+  };
 });

docs/app/js/app.js

@@ -164,6 +164,14 @@ <h2 class="md-toolbar-item md-breadcrumb md-headline">
           <a href="http://creativecommons.org/licenses/by/4.0/"  target="_blank" class="md-default-theme md-accent">CC BY 4.0</a>.
         </div>
       </div>
+
+      <md-button class="md-fab md-fab-bottom-right docs-scroll-fab"
+                 docs-scroll-class="scrolling"
+                 ng-click="scrollTop()"
+                 aria-label="Jump to top">
+        <md-icon md-svg-src="img/icons/ic_arrow_up_24px.svg"></md-icon>
+      </md-button>
+
     </md-content>
 
   </div>

docs/config/template/index.template.html

@@ -792,10 +792,11 @@ function UtilFactory($document, $timeout, $compile, $rootScope, $$mdAnimate, $in
     /**
      * Animate the requested element's scrollTop to the requested scrollPosition with basic easing.
      *
-     * @param element The element to scroll.
-     * @param scrollEnd The new/final scroll position.
+     * @param {!HTMLElement} element The element to scroll.
+     * @param {number} scrollEnd The new/final scroll position.
+     * @param {number=} duration Duration of the scroll. Default is 1000ms.
      */
-    animateScrollTo: function(element, scrollEnd) {
+    animateScrollTo: function(element, scrollEnd, duration) {
       var scrollStart = element.scrollTop;
       var scrollChange = scrollEnd - scrollStart;
       var scrollingDown = scrollStart < scrollEnd;
@@ -814,10 +815,10 @@ function UtilFactory($document, $timeout, $compile, $rootScope, $$mdAnimate, $in
       }
 
       function calculateNewPosition() {
-        var duration = 1000;
+        var easeDuration = duration || 1000;
         var currentTime = $mdUtil.now() - startTime;
 
-        return ease(currentTime, scrollStart, scrollChange, duration);
+        return ease(currentTime, scrollStart, scrollChange, easeDuration);
       }
 
       function ease(currentTime, start, change, duration) {