fix(tabs): md-center-tabs causes in high CPU usage (#11375)

<!-- 
Filling out this template is required! Do not delete it when submitting a Pull Request! Without this information, your Pull Request may be auto-closed.
-->
## PR Checklist
Please check that your PR fulfills the following requirements:
- [x] The commit message follows [our guidelines](https://github.com/angular/material/blob/master/.github/CONTRIBUTING.md#-commit-message-format)
- [ ] Tests for the changes have been added or this is not a bug fix / enhancement
- [x] Docs have been added, updated, or were not required

## PR Type
What kind of change does this PR introduce?
<!-- Please check the one that applies to this PR using "x". -->
```
[x] Bugfix
[ ] Enhancement
[ ] Documentation content changes
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Infrastructure changes
[ ] Other... Please describe:
```

## What is the current behavior?
`md-center-tabs` causes constant 30-50% CPU usage due to indefinite execution of `updateInkBarStyles()`;

<!-- Please describe the current behavior that you are modifying and link to one or more relevant issues. -->
Issue Number: 
Fixes #9690. Fixes #6375.

## What is the new behavior?

- make updateInkBarStyles() a noop if md-no-ink-bar is set
- remove md-no-ink docs as the feature does not exist
- clean up md-tab docs
- add JSDoc and improve comments in TabsController
- add TODOs for min/max widths that no longer match the latest MD spec
- update URLs to MD spec

## Does this PR introduce a breaking change?
```
[ ] Yes
[x] No
```
<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. -->
<!-- Note that breaking changes are highly unlikely to get merged to master unless the validation is clear and the use case is critical. -->

## Other information

Author: Splaktar

src/components/tabs/js/tabDirective.js

@@ -6,43 +6,50 @@
  * @restrict E
  *
  * @description
- * The `<md-tab>` is a nested directive used within `<md-tabs>` to specify a tab with a **label** and optional *view content*.
+ * The `<md-tab>` is a nested directive used within `<md-tabs>` to specify a tab with a **label**
+ * and optional *view content*.
  *
- * If the `label` attribute is not specified, then an optional `<md-tab-label>` tag can be used to specify more
- * complex tab header markup. If neither the **label** nor the **md-tab-label** are specified, then the nested
- * markup of the `<md-tab>` is used as the tab header markup.
+ * If the `label` attribute is not specified, then an optional `<md-tab-label>` tag can be used to
+ * specify more complex tab header markup. If neither the **label** nor the **md-tab-label** are
+ * specified, then the nested markup of the `<md-tab>` is used as the tab header markup.
  *
- * Please note that if you use `<md-tab-label>`, your content **MUST** be wrapped in the `<md-tab-body>` tag.  This
- * is to define a clear separation between the tab content and the tab label.
+ * Please note that if you use `<md-tab-label>`, your content **MUST** be wrapped in the
+ * `<md-tab-body>` tag.  This is to define a clear separation between the tab content and the tab
+ * label.
  *
- * This container is used by the TabsController to show/hide the active tab's content view. This synchronization is
- * automatically managed by the internal TabsController whenever the tab selection changes. Selection changes can
- * be initiated via data binding changes, programmatic invocation, or user gestures.
+ * This container is used by the TabsController to show/hide the active tab's content view. This
+ * synchronization is automatically managed by the internal TabsController whenever the tab
+ * selection changes. Selection changes can be initiated via data binding changes, programmatic
+ * invocation, or user gestures.
  *
  * @param {string=} label Optional attribute to specify a simple string as the tab label
- * @param {boolean=} ng-disabled If present and expression evaluates to truthy, disabled tab selection.
- * @param {expression=} md-on-deselect Expression to be evaluated after the tab has been de-selected.
+ * @param {boolean=} ng-disabled If present and expression evaluates to truthy, disabled tab
+ *  selection.
+ * @param {expression=} md-on-deselect Expression to be evaluated after the tab has been
+ *  de-selected.
  * @param {expression=} md-on-select Expression to be evaluated after the tab has been selected.
- * @param {boolean=} md-active When true, sets the active tab.  Note: There can only be one active tab at a time.
+ * @param {boolean=} md-active When true, sets the active tab.  Note: There can only be one active
+ *  tab at a time.
  *
  *
  * @usage
  *
  * <hljs lang="html">
- * <md-tab label="" ng-disabled md-on-select="" md-on-deselect="" >
+ * <md-tab label="My Tab" ng-disabled md-on-select="onSelect()" md-on-deselect="onDeselect()">
  *   <h3>My Tab content</h3>
  * </md-tab>
  *
- * <md-tab >
+ * <md-tab>
  *   <md-tab-label>
- *     <h3>My Tab content</h3>
+ *     <h3>My Tab</h3>
  *   </md-tab-label>
  *   <md-tab-body>
  *     <p>
- *       Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
- *       totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae
- *       dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit,
- *       sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
+ *       Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque
+ *       laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi
+ *       architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit
+ *       aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione
+ *       voluptatem sequi nesciunt.
  *     </p>
  *   </md-tab-body>
  * </md-tab>

src/components/tabs/js/tabsController.js

@@ -6,7 +6,7 @@ angular
  * @ngInject
  */
 function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipple, $mdUtil,
-                           $animateCss, $attrs, $compile, $mdTheming, $mdInteraction,
+                           $animateCss, $attrs, $compile, $mdTheming, $mdInteraction, $timeout,
                            MdTabsPaginationService) {
   // define private properties
   var ctrl      = this,
@@ -44,7 +44,8 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * AngularJS Lifecycle hook for newer AngularJS versions.
-   * Bindings are not guaranteed to have been assigned in the controller, but they are in the $onInit hook.
+   * Bindings are not guaranteed to have been assigned in the controller, but they are in the
+   * $onInit hook.
    */
   function $onInit() {
     // Define one-way bindings
@@ -141,10 +142,10 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   }
 
   /**
-   * Defines boolean attributes with default value set to true.  (ie. md-stretch-tabs with no value
-   * will be treated as being truthy)
-   * @param key
-   * @param handler
+   * Defines boolean attributes with default value set to true. I.e. md-stretch-tabs with no value
+   * will be treated as being truthy.
+   * @param {string} key
+   * @param {Function} handler
    */
   function defineBooleanAttribute (key, handler) {
     var attr = $attrs.$normalize('md-' + key);
@@ -167,19 +168,25 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   // Change handlers
 
   /**
-   * Toggles stretch tabs class and updates inkbar when tab stretching changes
-   * @param stretchTabs
+   * Toggles stretch tabs class and updates inkbar when tab stretching changes.
    */
-  function handleStretchTabs (stretchTabs) {
+  function handleStretchTabs () {
     var elements = getElements();
     angular.element(elements.wrapper).toggleClass('md-stretch-tabs', shouldStretchTabs());
     updateInkBarStyles();
   }
 
-  function handleCenterTabs (newValue) {
+  /**
+   * Update the value of ctrl.shouldCenterTabs.
+   */
+  function handleCenterTabs () {
     ctrl.shouldCenterTabs = shouldCenterTabs();
   }
 
+  /**
+   * @param {number} newWidth new max tab width in pixels
+   * @param {number} oldWidth previous max tab width in pixels
+   */
   function handleMaxTabWidth (newWidth, oldWidth) {
     if (newWidth !== oldWidth) {
       var elements = getElements();
@@ -246,8 +253,8 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Update the UI whenever the selected index changes. Calls user-defined select/deselect methods.
-   * @param newValue
-   * @param oldValue
+   * @param {number} newValue selected index's new value
+   * @param {number} oldValue selected index's previous value
    */
   function handleSelectedIndexChange (newValue, oldValue) {
     if (newValue === oldValue) return;
@@ -295,7 +302,7 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Handle user keyboard interactions
-   * @param event
+   * @param {KeyboardEvent} event keydown event
    */
   function keydown (event) {
     switch (event.keyCode) {
@@ -384,21 +391,27 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
     });
   }
 
+  /**
+   * Hides or shows the tabs ink bar.
+   * @param {boolean} hide A Boolean (not just truthy/falsy) value to determine whether the class
+   * should be added or removed.
+   */
   function handleInkBar (hide) {
     angular.element(getElements().inkBar).toggleClass('ng-hide', hide);
   }
 
   /**
-   * Toggle dynamic height class when value changes
-   * @param value
+   * Enables or disables tabs dynamic height.
+   * @param {boolean} value A Boolean (not just truthy/falsy) value to determine whether the class
+   * should be added or removed.
    */
   function handleDynamicHeight (value) {
     $element.toggleClass('md-dynamic-height', value);
   }
 
   /**
    * Remove a tab from the data and select the nearest valid tab.
-   * @param tabData
+   * @param {Object} tabData tab to remove
    */
   function removeTab (tabData) {
     if (destroyed) return;
@@ -419,8 +432,8 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Create an entry in the tabs array for a new tab at the specified index.
-   * @param tabData
-   * @param index
+   * @param {Object} tabData tab to insert
+   * @param {number} index location to insert the new tab
    * @returns {*}
    */
   function insertTab (tabData, index) {
@@ -583,9 +596,9 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   /**
    * Defines a property using a getter and setter in order to trigger a change handler without
    * using `$watch` to observe changes.
-   * @param key
-   * @param handler
-   * @param value
+   * @param {PropertyKey} key
+   * @param {Function} handler
+   * @param {any} value
    */
   function defineProperty (key, handler, value) {
     Object.defineProperty(ctrl, key, {
@@ -608,12 +621,16 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Calculates the width of the pagination wrapper by summing the widths of the dummy tabs.
-   * @returns {number}
+   * @returns {number} the width of the pagination wrapper in pixels
    */
   function calcPagingWidth () {
     return calcTabsWidth(getElements().tabs);
   }
 
+  /**
+   * @param {Array<HTMLElement>} tabs tab item elements for use in computing total width
+   * @returns {number} the width of the tabs in the specified array in pixels
+   */
   function calcTabsWidth(tabs) {
     var width = 0;
 
@@ -628,25 +645,35 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
     return Math.ceil(width);
   }
 
-  function getMaxTabWidth () {
+  /**
+   * @returns {number} either the max width as constrained by the container or the max width from an
+   * old version of the Material Design spec.
+   * TODO update max tab width to equal the spec in 1.2.
+   */
+  function getMaxTabWidth() {
     var elements = getElements(),
-        containerWidth = elements.canvas.clientWidth,
+      containerWidth = elements.canvas.clientWidth,
 
-        // See https://material.google.com/components/tabs.html#tabs-specs
-        specMax = 264;
+      // See https://material.io/design/components/tabs.html#spec which has been updated to 360px.
+      specMax = 264;
 
     // Do the spec maximum, or the canvas width; whichever is *smaller* (tabs larger than the canvas
     // width can break the pagination) but not less than 0
     return Math.max(0, Math.min(containerWidth - 1, specMax));
   }
 
+  /**
+   * @returns {number} the min width from an old version of the Material Design spec. This returns
+   * a larger min width if the container width is larger than 600px.
+   * TODO update min tab width to equal the spec in 1.2.
+   */
   function getMinTabWidth() {
     var elements = getElements(),
-        containerWidth = elements.canvas.clientWidth,
-        xsBreakpoint = 600,
+      containerWidth = elements.canvas.clientWidth,
+      xsBreakpoint = 600,
 
-        // See https://material.google.com/components/tabs.html#tabs-specs
-        specMin = containerWidth > xsBreakpoint ? 160 : 72;
+      // See https://material.io/design/components/tabs.html#spec which has been updated to 90px.
+      specMin = containerWidth > xsBreakpoint ? 160 : 72;
 
     // Do the spec minimum, or the canvas width; whichever is *smaller* (tabs larger than the canvas
     // width can break the pagination) but not less than 0
@@ -668,8 +695,9 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   }
 
   /**
-   * This moves the selected or focus index left or right.  This is used by the keydown handler.
-   * @param inc
+   * This moves the selected or focus index left or right. This is used by the keydown handler.
+   * @param {number} inc amount to increment
+   * @param {boolean} focus true to increment the focus index, false to increment the selected index
    */
   function incrementIndex (inc, focus) {
     var newIndex,
@@ -687,7 +715,7 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   }
 
   /**
-   * This is used to forward focus to tab container elements.  This method is necessary to avoid
+   * This is used to forward focus to tab container elements. This method is necessary to avoid
    * animation issues when attempting to focus an item that is out of view.
    */
   function redirectFocus () {
@@ -697,6 +725,7 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Forces the pagination to move the focused tab into view.
+   * @param {number} index of tab to have its offset adjusted
    */
   function adjustOffset (index) {
     var elements = getElements();
@@ -728,7 +757,7 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
   }
 
   /**
-   * Iterates through all queued functions and clears the queue.  This is used for functions that
+   * Iterates through all queued functions and clears the queue. This is used for functions that
    * are called before the UI is ready, such as size calculations.
    */
   function processQueue () {
@@ -740,9 +769,10 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
    * Determines if the tab content area is needed.
    */
   function updateHasContent () {
-    var hasContent  = false;
+    var hasContent = false;
+    var i;
 
-    for (var i = 0; i < ctrl.tabs.length; i++) {
+    for (i = 0; i < ctrl.tabs.length; i++) {
       if (ctrl.tabs[i].hasContent) {
         hasContent = true;
         break;
@@ -784,7 +814,9 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
       currentHeight -= tabsHeight;
       newHeight -= tabsHeight;
       // Need to include bottom border in these calculations
-      if ($element.attr('md-border-bottom') !== undefined) ++currentHeight;
+      if ($element.attr('md-border-bottom') !== undefined) {
+        ++currentHeight;
+      }
     }
 
     // Lock during animation so the user can't change tabs
@@ -825,20 +857,33 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
 
   /**
    * Repositions the ink bar to the selected tab.
-   * @returns {*}
-   */
-  function updateInkBarStyles () {
+   * Parameters are used when calling itself recursively when md-center-tabs is used as we need to
+   * run two passes to properly center the tabs. These parameters ensure that we only run two passes
+   * and that we don't run indefinitely.
+   * @param {number=} previousTotalWidth previous width of pagination wrapper
+   * @param {number=} previousWidthOfTabItems previous width of all tab items
+   */
+  function updateInkBarStyles (previousTotalWidth, previousWidthOfTabItems) {
+    if (ctrl.noInkBar) {
+      return;
+    }
     var elements = getElements();
 
     if (!elements.tabs[ ctrl.selectedIndex ]) {
       angular.element(elements.inkBar).css({ left: 'auto', right: 'auto' });
       return;
     }
 
-    if (!ctrl.tabs.length) return queue.push(ctrl.updateInkBarStyles);
-    // if the element is not visible, we will not be able to calculate sizes until it is
-    // we should treat that as a resize event rather than just updating the ink bar
-    if (!$element.prop('offsetParent')) return handleResizeWhenVisible();
+    if (!ctrl.tabs.length) {
+      queue.push(ctrl.updateInkBarStyles);
+      return;
+    }
+    // If the element is not visible, we will not be able to calculate sizes until it becomes
+    // visible. We should treat that as a resize event rather than just updating the ink bar.
+    if (!$element.prop('offsetParent')) {
+      handleResizeWhenVisible();
+      return;
+    }
 
     var index      = ctrl.selectedIndex,
         totalWidth = elements.paging.offsetWidth,
@@ -847,11 +892,14 @@ function MdTabsController ($scope, $element, $window, $mdConstant, $mdTabInkRipp
         right      = totalWidth - left - tab.offsetWidth;
 
     if (ctrl.shouldCenterTabs) {
-      // We need to use the same calculate process as in the pagination wrapper, to avoid rounding deviations.
-      var tabWidth = calcTabsWidth(elements.tabs);
-
-      if (totalWidth > tabWidth) {
-        $mdUtil.nextTick(updateInkBarStyles, false);
+      // We need to use the same calculate process as in the pagination wrapper, to avoid rounding
+      // deviations.
+      var totalWidthOfTabItems = calcTabsWidth(elements.tabs);
+
+      if (totalWidth > totalWidthOfTabItems &&
+          previousTotalWidth !== totalWidth &&
+          previousWidthOfTabItems !== totalWidthOfTabItems) {
+        $timeout(updateInkBarStyles, 0, true, totalWidth, totalWidthOfTabItems);
       }
     }
     updateInkBarClassName();