add docs

Author: Narretz

docs/content/error/ngModel/numfmt.ngdoc

@@ -3,7 +3,7 @@
 @fullName Model is not of type `number`
 @description
 
-The number input directive `<input type="number">` requires the model to be a `number`.
+The `input[number]` and `input[range]` directives require the model to be a `number`.
 
 If the model is something else, this error will be thrown.
 

karma-shared.conf.js

@@ -17,7 +17,7 @@ module.exports = function(config, specificOptions) {
       testName: specificOptions.testName || 'AngularJS',
       startConnect: true,
       options: {
-        // We need selenium version +2.46 for Firefox 39 and the last selenium version for OS X is 2.45.
+        // We need selenium version +2.46 for 'Firefox' 39 and the last selenium version for OS X is 2.45.
         // TODO: Uncomment when there is a selenium 2.46 available for OS X.
         // 'selenium-version': '2.46.0'
       }

src/ng/directive/input.js

@@ -1036,22 +1036,49 @@ var inputType = {
    * @name input[range]
    *
    * @description
-   * Native range input with validation and transformation. Sets the `number` validation
-   * to always have a valid number. Note that IE9 does not support the `range` type, but falls back
+   * Native range input with validation and transformation.
+   *
+   * The model for the range input must always be a `Number`.
+   *
+   * IE9 does not support the `range` type, but falls back
    * to a text input. Model binding, validation and number parsing are nevertheless supported.
    *
-   * @param {string} ngModel Assignable angular expression to data-bind to.
+   * Browsers that support range (latest Chrome, Safari, Firefox, Edge) treat `input[range]`
+   * in a way that never allows the input to hold an invalid value. That means:
+   * - any non-numerical value is set to `(max + min) / 2`.
+   * - any numerical value that is less than the current min val, or greater than the current max val
+   * is set to the min / max val respectively.
+   *
+   * This has the following consequences for Angular:
+   *
+   * Since the element value should always reflect the current model value, a range input
+   * will set the bound ngModel expression to the value that the browser has set for the
+   * input element. For example, in the following input `<input type="range" ng-model="model.value">`,
+   * if I set `model.value = null`, the browser will set the input to `'50'`. Angular will then set
+   * the model to `50`, to prevent input and model value being out of sync.
+   *
+   * This does not only affect changes to the model value, but also to the values of the `min` and
+   * `max` attributes. When these change in a way that will cause the browser to modify the input value,
+   * Angular will also update the model value.
+   *
+   * Automatic value adjustment also means that a range input element can never have the `required`,
+   * `min`, or `max` errors, except when using `ngMax` and `ngMin`, which are not affected by automatic
+   * value adjustment, because they do not set the `min` and `max` attributes.
+   *
+   * @param {string}  ngModel Assignable angular expression to data-bind to.
    * @param {string=} name Property name of the form under which the control is published.
    * @param {string=} min Sets the `min` validation to ensure that the value entered is greater
    *                  than `min`. Can be interpolated.
    * @param {string=} max Sets the `max` validation to ensure that the value entered is less than `max`.
    *                  Can be interpolated.
    * @param {string=} ngMin Takes an expression. Sets the `min` validation to ensure that the value
    *                  entered is greater than `min`. Does not set the `min` attribute and therefore
-   *                  adds no native HTML5 validation.
+   *                  adds no native HTML5 validation. It also means the browser won't adjust the
+   *                  element value in case `min` is greater than the current value.
    * @param {string=} ngMax Takes an expression. Sets the `max` validation to ensure that the value
    *                  entered is less than `max`. Does not set the `min` attribute and therefore
-   *                  adds no native HTML5 validation.
+   *                  adds no native HTML5 validation. It also means the browser won't adjust the
+   *                  element value in case `max` is less than the current value.
    * @param {string=} ngChange Angular expression to be executed when the ngModel value changes due
    *                  to user interaction with the input element.
    *
@@ -1062,18 +1089,52 @@ var inputType = {
            angular.module('rangeExample', [])
              .controller('ExampleController', ['$scope', function($scope) {
                $scope.value = 75;
+               $scope.min = 10;
+               $scope.max = 90;
              }]);
          </script>
          <form name="myForm" ng-controller="ExampleController">
-           Number: <input type="range" name="input" ng-model="value"
-                          min="10" max="90">
-           <tt>value = {{value}}</tt><br/>
-           <tt>myForm.input.$valid = {{myForm.input.$valid}}</tt><br/>
-           <tt>myForm.input.$error = {{myForm.input.$error}}</tt><br/>
-           <tt>myForm.$valid = {{myForm.$valid}}</tt><br/>
+
+           Model as range: <input type="range" name="range" ng-model="value"
+                          min="{{min}}"  max="{{max}}">
+          <hr>
+          Model as number: <input type="number" ng-model="value"><br>
+          Min: <input type="number" ng-model="min"><br>
+          Max: <input type="number" ng-model="min"><br>
+           value = <code>{{value}}</code><br/>
+           myForm.range.$valid = <code>{{myForm.range.$valid}}</code><br/>
+           myForm.range.$error = <code>{{myForm.range.$error}}</code>
+          </form>
+        </file>
+      </example>
+
+   * ## Range Input with ngMin & ngMax attributes
+
+   * @example
+      <example name="range-input-directive-ng" module="rangeExample">
+        <file name="index.html">
+         <script>
+           angular.module('rangeExample', [])
+             .controller('ExampleController', ['$scope', function($scope) {
+               $scope.value = 75;
+               $scope.min = 10;
+               $scope.max = 90;
+             }]);
+         </script>
+         <form name="myForm" ng-controller="ExampleController">
+           Model as range: <input type="range" name="range" ng-model="value"
+                          ng-min="10" ng-max="90">
+          <hr>
+          Model as number: <input type="number" ng-model="value"><br>
+           Min: <input type="number" ng-model="min"><br>
+           Max: <input type="number" ng-model="min"><br>
+           value = <code>{{value}}</code><br/>
+           myForm.range.$valid = <code>{{myForm.range.$valid}}</code><br/>
+           myForm.range.$error = <code>{{myForm.range.$error}}</code>
           </form>
         </file>
       </example>
+
    */
   'range': rangeInputType,
 
@@ -1528,32 +1589,32 @@ function rangeInputType(scope, element, attr, ctrl, $sniffer, $browser) {
       return;
     }
 
-    // TODO(matsko): implement validateLater to reduce number of validations
     if (supportsRange && minAttrType === 'min') {
       var elVal = element.val();
-      // IE11 doesn't set the el val correctly if the maxVal is less than the element value
+      // IE11 doesn't set the el val correctly if the minVal is greater than the element value
       if (minVal > elVal) {
         element.val(minVal);
       }
       ctrl.$setViewValue(element.val());
     } else {
+      // TODO(matsko): implement validateLater to reduce number of validations
       ctrl.$validate();
     }
   }
 
   var minAttrType = isDefined(attr.min) ? 'min' : attr.ngMin ? 'ngMin' : false;
   if (minAttrType) {
-    // Since ngMin doesn't set the min attr, the browser doesn't adjust the input value as setting min would
     ctrl.$validators.min = isDefined(attr.min) && supportsRange ?
       function noopMinValidator(value) {
         // Since all browsers set the input to a valid value, we don't need to check validity
         return true;
       } :
+      // ngMin doesn't set the min attr, so the browser doesn't adjust the input value as setting min would
       function minValidator(modelValue, viewValue) {
         return ctrl.$isEmpty(viewValue) || isUndefined(minVal) || viewValue >= minVal;
       };
 
-    // Assign minVal when the directive is linked. This won't $validate as the model isn't ready yet
+    // Assign minVal when the directive is linked. This won't run the validators as the model isn't ready yet
     minChange(attr.min);
     attr.$observe('min', minChange);
   }
@@ -1563,7 +1624,6 @@ function rangeInputType(scope, element, attr, ctrl, $sniffer, $browser) {
       val = parseFloat(val);
     }
     maxVal = isNumber(val) && !isNaN(val) ? val : undefined;
-    // TODO(matsko): implement validateLater to reduce number of validations
     // ignore changes before model is initialized
     if (isNumber(ctrl.$modelValue) && isNaN(ctrl.$modelValue)) {
       return;
@@ -1577,22 +1637,23 @@ function rangeInputType(scope, element, attr, ctrl, $sniffer, $browser) {
       }
       ctrl.$setViewValue(element.val());
     } else {
+      // TODO(matsko): implement validateLater to reduce number of validations
       ctrl.$validate();
     }
   }
   var maxAttrType = isDefined(attr.max) ? 'max' : attr.ngMax ? 'ngMax' : false;
   if (maxAttrType) {
-    // Since ngMax doesn't set the max attr, the browser doesn't adjust the input value as setting max would
     ctrl.$validators.max = isDefined(attr.max) && supportsRange ?
       function noopMaxValidator() {
         // Since all browsers set the input to a valid value, we don't need to check validity
         return true;
       } :
+      // ngMax doesn't set the max attr, so the browser doesn't adjust the input value as setting max would
       function maxValidator(modelValue, viewValue) {
         return ctrl.$isEmpty(viewValue) || isUndefined(maxVal) || viewValue <= maxVal;
       };
 
-    // Assign maxVal when the directive is linked. This won't $validate as the model isn't ready yet
+    // Assign maxVal when the directive is linked. This won't run the validators as the model isn't ready yet
     maxChange(attr.max);
     attr.$observe('max', maxChange);
   }

test/ng/directive/inputSpec.js

@@ -2823,12 +2823,18 @@ describe('input', function() {
 
     var scope;
 
+    var rangeTestEl = angular.element('<input type="range">');
+    var supportsRange = rangeTestEl[0].type === 'range';
     beforeEach(function() {
       scope = $rootScope;
     });
 
-    var rangeTestEl = angular.element('<input type="range">');
-    var supportsRange = rangeTestEl[0].type === 'range';
+    it('should parse the input value to a Number', function() {
+      var inputElm = helper.compileInput('<input type="range" ng-model="age" />');
+
+      helper.changeInputValueTo('75');
+      expect(scope.age).toBe(75);
+    });
 
     if (supportsRange) {
       // This behavior only applies to browsers that implement the range input, which do not