docs(app): refactor the Docs App based on the MD prototype

I incorporated the prototype detailed in gkalpak#3.

Things that are different from the prototype (besides using actual data):

 * The left sidenav (toc) is not styled properly (or even readably).
 * The subheaders in the left sidenav are not "stickying" properly (only `ng` becomes sticky).
 * Icons are missing (since we are not using FontAwesome). E.g. search-fab, toc-toggle, results
 * In the right sidenav (search) there are some unwanted horizontal scrollbars.
   (This section probably needs rethinking anyway.)
 * I have implemented a `responsiveMenu` directive to show the options in the header-menus
   (Learn/Develop/Discuss). The purpose is to show the options in a "dropdown-ish" menu on larger
   screens and using a BottomSheet on smaller. At the moment a BottomSheet is used on every
   screen-size.

Notes:

 - Still no version-picker and breadcrumbs (I have left the original implementation of those two
   commented out).
 - I have replaced the previous docs.css with a new one containing the style of the prototype.
   I have renamed the old one to `docs_old.css` and left it there temporarily for quick reference.
   We need to clean up this and the rest of the old CSS files.
 - The main content area is totally unstyled and needs some love (a lot actually).

I have also "sprinkled" the code with a few more TODOs/FIXMEs.

(For more details on known issues and missing features take a look at
 gkalpak#3)

Author: gkalpak

Diff for: docs/app/assets/css/docs.css

@@ -1,11 +1,11 @@
 'use strict';
 
 angular.module('docsApp', [
-  'ngRoute',
-  'ngCookies',
-  'ngSanitize',
-  'ngAnimate',
+  'ngMaterial',
+  'HeaderController',
+  'FooterController',
   'DocsController',
+  'ViewUtils',
   'versionsData',
   'pagesData',
   'navData',
@@ -15,8 +15,7 @@ angular.module('docsApp', [
   'search',
   'tutorials',
   'versions',
-  'bootstrap',
-  'ui.bootstrap.dropdown'
+  'responsiveMenu'
 ])
 
 .config(['$locationProvider', function($locationProvider) {

Diff for: docs/app/assets/css/docs_old.css

@@ -1,17 +1,29 @@
 angular.module('directives', [])
 
 /**
- * backToTop Directive
- * @param  {Function} $anchorScroll
+ * scrollTo Directive
  *
- * @description Ensure that the browser scrolls when the anchor is clicked
+ * @description
+ * Upon click, scroll to the target element (identified by the selector provided via the `scroll-to`
+ * attribute).
  */
-.directive('backToTop', ['$anchorScroll', '$location', function($anchorScroll, $location) {
-  return function link(scope, element) {
-    element.on('click', function(event) {
-      $location.hash('');
-      $anchorScroll();
-    });
+.directive('scrollTo', ['$document', '$location', function($document, $location) {
+  var doc = $document[0];
+
+  return {
+    restrict: 'A',
+    link: function scrollToPostLink(scope, elem, attrs) {
+      elem.on('click', onClick);
+
+      function onClick() {
+        var targetSelector = attrs.scrollTo;
+        var targetElem = doc.querySelector(targetSelector);
+
+        if (targetElem) {
+          targetElem.scrollIntoView();
+        }
+      }
+    }
   };
 }])
 
@@ -30,6 +42,7 @@ angular.module('directives', [])
   };
 }])
 
+
 .directive('scrollYOffsetElement', ['$anchorScroll', function($anchorScroll) {
   return function(scope, element) {
     $anchorScroll.yOffset = element;

Diff for: docs/app/src/app.js

@@ -1,11 +1,13 @@
-angular.module('DocsController', [])
+angular.module('DocsController', ['ViewUtils'])
 
 .controller('DocsController', [
-          '$scope', '$rootScope', '$location', '$window', '$cookies', 'openPlunkr',
+          '$scope', '$rootScope', '$location', '$window', 'openPlunkr', 'ViewUtils',
               'NG_PAGES', 'NG_NAVIGATION', 'NG_VERSION',
-  function($scope, $rootScope, $location, $window, $cookies, openPlunkr,
+  function($scope, $rootScope, $location, $window, openPlunkr, ViewUtils,
               NG_PAGES, NG_NAVIGATION, NG_VERSION) {
 
+  $scope.vu = ViewUtils;
+
   $scope.openPlunkr = openPlunkr;
 
   $scope.docsVersion = NG_VERSION.isSnapshot ? 'snapshot' : NG_VERSION.version;
@@ -53,8 +55,6 @@ angular.module('DocsController', [])
    Initialize
    ***********************************/
 
-  $scope.versionNumber = angular.version.full;
-  $scope.version = angular.version.full + "  " + angular.version.codeName;
   $scope.loading = 0;
 
 

Diff for: docs/app/src/directives.js

@@ -0,0 +1,10 @@
+angular.
+    module('FooterController', []).
+    controller('FooterController', FooterController);
+
+FooterController.$inject = [];
+function FooterController() {
+  var v = angular.version;
+  this.versionNumber = v.full;
+  this.version = v.full + '  ' + v.codeName;
+}

Diff for: docs/app/src/docs.js

@@ -0,0 +1,35 @@
+angular.
+    module('HeaderController', []).
+    controller('HeaderController', HeaderController);
+
+HeaderController.$inject = [];
+function HeaderController() {
+  this.learnItems = [
+    {label: 'Why AngularJS?', url: '//angularjs.org/'},
+    {label: 'Watch', url: '//www.youtube.com/user/angularjs'},
+    {label: 'Tutorial', url: 'tutorial'},
+    {label: 'Case Studies', url: '//builtwith.angularjs.org/'},
+    {label: 'Seed App project template', url: '//github.com/angular/angular-seed'},
+    {label: 'FAQ', url: 'misc/faq'}
+  ];
+
+  this.developItems = [
+    {label: 'Why AngularJS?', url: '//angularjs.org/'},
+    {label: 'Tutorial', url: 'tutorial'},
+    {label: 'Developer Guide', url: 'guide'},
+    {label: 'API Reference', url: 'api'},
+    {label: 'Error Reference', url: 'error'},
+    {label: 'Contribute', url: 'misc/contribute'},
+    {label: 'Download', url: '//code.angularjs.org/'}
+  ];
+
+  this.discussItems = [
+    {label: 'Blog', url: '//blog.angularjs.org'},
+    {label: 'Mailing List', url: '//groups.google.com/group/angular'},
+    {label: 'Chat Room', url: '//webchat.freenode.net/?channels=angularjs&uio=d4'},
+    {label: 'Twitter', url: '//twitter.com/#!/angularjs'},
+    {label: 'Google+', url: '//plus.google.com/110323587230527980117'},
+    {label: 'GitHub', url: '//github.com/angular/angular.js'},
+    {label: 'Issue Tracker', url: '//github.com/angular/angular.js/issues'},
+  ];
+}

Diff for: docs/app/src/footer-conroller.js

@@ -0,0 +1,55 @@
+angular.
+    module('responsiveMenu', ['ngMaterial', 'ViewUtils']).
+    directive('responsiveMenu', responsiveMenuDirective);
+
+responsiveMenuDirective.$inject = ['$mdBottomSheet', 'ViewUtils'];
+function responsiveMenuDirective($mdBottomSheet, ViewUtils) {
+  // TODO: Create showFns for various sizes (not necessarily all)
+  var showFns = {
+    // 'gt-lg': '',
+    // 'lg': '',
+    // 'md': '',
+    'sm': function showSmFn(items) {
+      $mdBottomSheet.show({
+        template: _getResponsiveMenuSmTemplate(),
+        controller: ['$mdBottomSheet', '$scope',
+          function ResponsiveMenuSmController($mdBottomSheet, $scope) {
+            $scope.items = items;
+            $scope.onItemClick = $mdBottomSheet.hide.bind($mdBottomSheet);
+          }
+        ]
+      });
+    }
+  };
+
+  var defaultShowFn = showFns.sm;
+
+  return {
+    restrict: 'A',
+    scope: {
+      items: '=rmItems'
+    },
+    controller: ['$element', '$scope', function ResponsiveMenuController($element, $scope) {
+      $element.on('click', onClick.bind(this));
+
+      function onClick(evt) {
+        var showFn = ViewUtils.getValueForSize(showFns, defaultShowFn);
+        showFn($scope.items);
+      }
+    }]
+  };
+}
+
+function _getResponsiveMenuSmTemplate() {
+  return [
+    '<md-bottom-sheet>',
+    '  <md-list>',
+    '    <md-item ng-repeat="item in items">',
+    '      <md-button aria-label="{{item.label}}" ng-click="onItemClick(item)">',
+    '        <a ng-href="{{item.url}}">{{item.label}}</a>',
+    '      </md-button>',
+    '    </md-item>',
+    '  </md-list>',
+    '</md-bottom-sheet>',
+    ''].join('\n');
+}

Diff for: docs/app/src/header-conroller.js

@@ -1,63 +1,84 @@
-angular.module('search', [])
+angular.module('search', ['ViewUtils'])
 
-.controller('DocsSearchCtrl', ['$scope', '$location', 'docsSearch', function($scope, $location, docsSearch) {
-  function clearResults() {
-    $scope.results = [];
-    $scope.colClassName = null;
-    $scope.hasResults = false;
-  }
+.controller('DocsSearchController', ['$scope', '$location', 'docsSearch', 'ViewUtils',
+  function($scope, $location, docsSearch, ViewUtils) {
+    $scope.hideResults = hideResults;
+    $scope.search = search;
+    $scope.submit = submit;
 
-  $scope.search = function(q) {
-    var MIN_SEARCH_LENGTH = 2;
-    if(q.length >= MIN_SEARCH_LENGTH) {
-      docsSearch(q).then(function(hits) {
-        var results = {};
-        angular.forEach(hits, function(hit) {
-          var area = hit.area;
+    // TODO: Probably use some event on the input field, when
+    // https://github.com/angular/material/pull/848 is resolved
+    $scope.$watch('q', search);
 
-          var limit = (area === 'api') ? 40 : 14;
-          results[area] = results[area] || [];
-          if(results[area].length < limit) {
-            results[area].push(hit);
-          }
-        });
+    clearResults();
 
-        var totalAreas = Object.keys(results).length;
-        if(totalAreas > 0) {
-          $scope.colClassName = 'cols-' + totalAreas;
-        }
-        $scope.hasResults = totalAreas > 0;
-        $scope.results = results;
-      });
-    } else {
-      clearResults();
+    function clearResults() {
+      $scope.results = {};
+      $scope.colClassName = null;
+      $scope.hasResults = false;
     }
-    if(!$scope.$$phase) $scope.$apply();
-  };
 
-  $scope.submit = function() {
-    var result;
-    if ($scope.results.api) {
-      result = $scope.results.api[0];
-    } else {
-      for(var i in $scope.results) {
-        result = $scope.results[i][0];
-        if(result) {
-          break;
-        }
+    function hideResults(path) {
+      ViewUtils.closeSidenav('search');
+      clearResults();
+      $scope.q = '';
+
+      if (arguments.length) {
+        $location.path(path);
       }
     }
-    if(result) {
-      $location.path(result.path);
-      $scope.hideResults();
+
+    function search(q) {
+      var MIN_SEARCH_LENGTH = 2;
+      q = q || '';
+
+      if (q.length >= MIN_SEARCH_LENGTH) {
+        docsSearch(q).then(function(hits) {
+          var results = {};
+          angular.forEach(hits, function(hit) {
+            var area = hit.area;
+
+            var limit = (area === 'api') ? 40 : 14;
+            results[area] = results[area] || [];
+            if(results[area].length < limit) {
+              results[area].push(hit);
+            }
+          });
+
+          var totalAreas = Object.keys(results).length;
+          if (totalAreas > 0) {
+            // TODO: Use `colClassName` or remove it
+            $scope.colClassName = 'cols-' + totalAreas;
+          }
+          $scope.hasResults = totalAreas > 0;
+          $scope.results = results;
+        });
+      } else {
+        clearResults();
+      }
+
+      // FIXME: Don't use private `$$phase` property
+      if (!$scope.$$phase) $scope.$apply();
     }
-  };
 
-  $scope.hideResults = function() {
-    clearResults();
-    $scope.q = '';
-  };
-}])
+    function submit() {
+      var result;
+
+      if ($scope.results.api) {
+        result = $scope.results.api[0];
+      } else {
+        Object.keys($scope.results).some(function(key) {
+          return (result = $scope.results[key][0]);
+        });
+      }
+
+      if (result) {
+        $location.path(result.path);
+        $scope.hideResults();
+      }
+    }
+  }
+])
 
 
 .controller('Error404SearchCtrl', ['$scope', '$location', 'docsSearch',
@@ -173,24 +194,25 @@ angular.module('search', [])
   };
 })
 
-.directive('focused', function($timeout) {
-  return function(scope, element, attrs) {
-    element[0].focus();
-    element.on('focus', function() {
-      scope.$apply(attrs.focused + '=true');
-    });
-    element.on('blur', function() {
-      // have to use $timeout, so that we close the drop-down after the user clicks,
-      // otherwise when the user clicks we process the closing before we process the click.
-      $timeout(function() {
-        scope.$eval(attrs.focused + '=false');
-      });
-    });
-    // TODO(gkalpak): Do we need this if we first register the listeners
-    //                and the call `.focus()` ?
-    scope.$eval(attrs.focused + '=true');
-  };
-})
+// TODO: Do we need this ?
+// .directive('focused', function($timeout) {
+//   return function(scope, element, attrs) {
+//     element[0].focus();
+//     element.on('focus', function() {
+//       scope.$apply(attrs.focused + '=true');
+//     });
+//     element.on('blur', function() {
+//       // have to use $timeout, so that we close the drop-down after the user clicks,
+//       // otherwise when the user clicks we process the closing before we process the click.
+//       $timeout(function() {
+//         scope.$eval(attrs.focused + '=false');
+//       });
+//     });
+//     // TODO(gkalpak): Do we need this if we first register the listeners
+//     //                and the call `.focus()` ?
+//     scope.$eval(attrs.focused + '=true');
+//   };
+// })
 
 .directive('docsSearchInput', ['$document', function($document) {
   var doc = $document[0];