feat(chips): md-max-chips to specify a maximum of chips that can be added through user input

Current UX provides no indication of when max chips has been reached.

* use ngMessages to show information at max limit condition.

Fixes #6864. Closes #6897.

Author: devversion

src/components/chips/chips.spec.js

@@ -409,6 +409,71 @@ describe('<md-chips>', function() {
         }));
       });
 
+      describe('md-max-chips', function() {
+
+        beforeEach(function() {
+          // Clear default items to test the max chips functionality
+          scope.items = [];
+        });
+
+        it('should not add a new chip if the max-chips limit is reached', function() {
+          var element = buildChips('<md-chips ng-model="items" md-max-chips="1"></md-chips>');
+          var ctrl = element.controller('mdChips');
+
+          element.scope().$apply(function() {
+            ctrl.chipBuffer = 'Test';
+            simulateInputEnterKey(ctrl);
+          });
+
+          expect(scope.items.length).toBe(1);
+
+          element.scope().$apply(function() {
+            ctrl.chipBuffer = 'Test 2';
+            simulateInputEnterKey(ctrl);
+          });
+
+          expect(scope.items.length).not.toBe(2);
+        });
+
+        it('should update the md-max-chips model validator for forms', function() {
+          var template =
+            '<form name="form">' +
+            '<md-chips name="chips" ng-model="items" md-max-chips="1"></md-chips>' +
+            '</form>';
+
+          var element = buildChips(template);
+          var ctrl = element.find('md-chips').controller('mdChips');
+
+          element.scope().$apply(function() {
+            ctrl.chipBuffer = 'Test';
+            simulateInputEnterKey(ctrl);
+          });
+
+          expect(scope.form.chips.$error['md-max-chips']).toBe(true);
+        });
+
+        it('should not reset the buffer if the maximum is reached', function() {
+          var element = buildChips('<md-chips ng-model="items" md-max-chips="1"></md-chips>');
+          var ctrl = element.controller('mdChips');
+
+          element.scope().$apply(function() {
+            ctrl.chipBuffer = 'Test';
+            simulateInputEnterKey(ctrl);
+          });
+
+          expect(scope.items.length).toBe(1);
+
+          element.scope().$apply(function() {
+            ctrl.chipBuffer = 'Test 2';
+            simulateInputEnterKey(ctrl);
+          });
+
+          expect(ctrl.chipBuffer).toBe('Test 2');
+          expect(scope.items.length).not.toBe(2);
+        });
+
+      });
+
       describe('md-autocomplete', function() {
         var AUTOCOMPLETE_CHIPS_TEMPLATE = '\
           <md-chips ng-model="items">\

src/components/chips/demoBasicUsage/index.html

@@ -3,12 +3,19 @@
   <md-content class="md-padding" layout="column">
     <h2 class="md-title">Use a custom chip template.</h2>
 
-    <md-chips ng-model="ctrl.roFruitNames" readonly="ctrl.readonly">
-      <md-chip-template>
-        <strong>{{$chip}}</strong>
-        <em>(fruit)</em>
-      </md-chip-template>
-    </md-chips>
+    <form name="fruitForm">
+      <md-chips ng-model="ctrl.roFruitNames" name="fruitName" readonly="ctrl.readonly" md-max-chips="5">
+        <md-chip-template>
+          <strong>{{$chip}}</strong>
+          <em>(fruit)</em>
+        </md-chip-template>
+      </md-chips>
+
+      <div class="errors" ng-messages="fruitForm.fruitName.$error">
+        <div ng-message="md-max-chips">The maxmium of chips is reached.</div>
+      </div>
+    </form>
+
 
     <br/>
     <h2 class="md-title">Use the default chip template.</h2>

src/components/chips/demoBasicUsage/script.js

@@ -1,7 +1,7 @@
 (function () {
   'use strict';
   angular
-      .module('chipsDemo', ['ngMaterial'])
+      .module('chipsDemo', ['ngMaterial', 'ngMessages'])
       .controller('BasicDemoCtrl', DemoCtrl);
 
   function DemoCtrl ($timeout, $q) {

src/components/chips/demoBasicUsage/style.scss

@@ -1,3 +1,9 @@
+.errors {
+  font-size: 12px;
+  color: rgb(221,44,0);
+  margin-top: 10px;
+}
+
 .custom-chips {
   .md-chip {
     position: relative;

src/components/chips/js/chipsController.js

@@ -137,6 +137,10 @@ MdChipsCtrl.prototype.inputKeydown = function(event) {
   if (this.separatorKeys.indexOf(event.keyCode) !== -1) {
     if ((this.hasAutocomplete && this.requireMatch) || !chipBuffer) return;
     event.preventDefault();
+
+    // Only append the chip and reset the chip buffer if the max chips limit isn't reached.
+    if (this.items.length >= this.maxChips) return;
+
     this.appendChip(chipBuffer);
     this.resetChipBuffer();
   }
@@ -242,7 +246,7 @@ MdChipsCtrl.prototype.appendChip = function(newChip) {
     var identical = this.items.some(function(item){
       return angular.equals(newChip, item);
     });
-    if(identical) return;
+    if (identical) return;
   }
 
   // Check for a null (but not undefined), or existing chip and cancel appending
@@ -251,6 +255,10 @@ MdChipsCtrl.prototype.appendChip = function(newChip) {
   // Append the new chip onto our list
   var index = this.items.push(newChip);
 
+  // Update model validation
+  this.ngModelCtrl.$setDirty();
+  this.validateModel();
+
   // If they provide the md-on-add attribute, notify them of the chip addition
   if (this.useOnAdd && this.onAdd) {
     this.onAdd({ '$chip': newChip, '$index': index });
@@ -350,13 +358,30 @@ MdChipsCtrl.prototype.resetChipBuffer = function() {
   }
 };
 
+MdChipsCtrl.prototype.hasMaxChips = function() {
+  if (angular.isString(this.maxChips)) this.maxChips = parseInt(this.maxChips, 10) || 0;
+
+  return this.maxChips > 0 && this.items.length >= this.maxChips;
+};
+
+/**
+ * Updates the validity properties for the ngModel.
+ */
+MdChipsCtrl.prototype.validateModel = function() {
+  this.ngModelCtrl.$setValidity('md-max-chips', !this.hasMaxChips());
+};
+
 /**
  * Removes the chip at the given index.
  * @param index
  */
 MdChipsCtrl.prototype.removeChip = function(index) {
   var removed = this.items.splice(index, 1);
 
+  // Update model validation
+  this.ngModelCtrl.$setDirty();
+  this.validateModel();
+
   if (removed && removed.length && this.useOnRemove && this.onRemove) {
     this.onRemove({ '$chip': removed[0], '$index': index });
   }

src/components/chips/js/chipsDirective.js

@@ -67,6 +67,9 @@
    *    displayed when there is at least on item in the list
    * @param {boolean=} readonly Disables list manipulation (deleting or adding list items), hiding
    *    the input and delete buttons
+   * @param {number=} md-max-chips The maximum number of chips allowed to add through user input.
+   *    <br/><br/>The validation property `md-max-chips` can be used when the max chips
+   *    amount is reached.
    * @param {expression} md-transform-chip An expression of form `myFunction($chip)` that when called
    *    expects one of the following return values:
    *    - an object representing the `$chip` input string
@@ -94,6 +97,23 @@
    *   </md-chips>
    * </hljs>
    *
+   * <h3>Validation</h3>
+   * When using [ngMessages](https://docs.angularjs.org/api/ngMessages), you can show errors based
+   * on our custom validators.
+   * <hljs lang="html">
+   *   <form name="userForm">
+   *     <md-chips
+   *       name="fruits"
+   *       ng-model="myItems"
+   *       placeholder="Add an item"
+   *       md-max-chips="5">
+   *     </md-chips>
+   *     <div ng-messages="userForm.fruits.$error" ng-if="userForm.$dirty">
+   *       <div ng-message="md-max-chips">You reached the maximum amount of chips</div>
+   *    </div>
+   *   </form>
+   * </hljs>
+   *
    */
 
 
@@ -175,6 +195,7 @@
         readonly: '=readonly',
         placeholder: '@',
         secondaryPlaceholder: '@',
+        maxChips: '@mdMaxChips',
         transformChip: '&mdTransformChip',
         onAppend: '&mdOnAppend',
         onAdd: '&mdOnAdd',