@angular-wave/angular.ts 0.0.67 → 0.0.69

package/src/directive/options/options.md

@@ -0,0 +1,179 @@
+/\*\*
+
+-
+- The `ngOptions` attribute can be used to dynamically generate a list of `<option>`
+- elements for the `<select>` element using the array or object obtained by evaluating the
+- `ngOptions` comprehension expression.
+-
+- In many cases, {@link ng.directive:ngRepeat ngRepeat} can be used on `<option>` elements instead of
+- `ngOptions` to achieve a similar result. However, `ngOptions` provides some benefits:
+- - more flexibility in how the `<select>`'s model is assigned via the `select` **`as`** part of the
+- comprehension expression
+- - reduced memory consumption by not creating a new scope for each repeated instance
+- - increased render speed by creating the options in a documentFragment instead of individually
+-
+- When an item in the `<select>` menu is selected, the array element or object property
+- represented by the selected option will be bound to the model identified by the `ngModel`
+- directive.
+-
+- Optionally, a single hard-coded `<option>` element, with the value set to an empty string, can
+- be nested into the `<select>` element. This element will then represent the `null` or "not selected"
+- option. See example below for demonstration.
+-
+- ## Complex Models (objects or collections)
+-
+- By default, `ngModel` watches the model by reference, not value. This is important to know when
+- binding the select to a model that is an object or a collection.
+-
+- One issue occurs if you want to preselect an option. For example, if you set
+- the model to an object that is equal to an object in your collection, `ngOptions` won't be able to set the selection,
+- because the objects are not identical. So by default, you should always reference the item in your collection
+- for preselections, e.g.: `$scope.selected = $scope.collection[3]`.
+-
+- Another solution is to use a `track by` clause, because then `ngOptions` will track the identity
+- of the item not by reference, but by the result of the `track by` expression. For example, if your
+- collection items have an id property, you would `track by item.id`.
+-
+- A different issue with objects or collections is that ngModel won't detect if an object property or
+- a collection item changes. For that reason, `ngOptions` additionally watches the model using
+- `$watchCollection`, when the expression contains a `track by` clause or the the select has the `multiple` attribute.
+- This allows ngOptions to trigger a re-rendering of the options even if the actual object/collection
+- has not changed identity, but only a property on the object or an item in the collection changes.
+-
+- Note that `$watchCollection` does a shallow comparison of the properties of the object (or the items in the collection
+- if the model is an array). This means that changing a property deeper than the first level inside the
+- object/collection will not trigger a re-rendering.
+-
+- ## `select` **`as`**
+-
+- Using `select` **`as`** will bind the result of the `select` expression to the model, but
+- the value of the `<select>` and `<option>` html elements will be either the index (for array data sources)
+- or property name (for object data sources) of the value within the collection. If a **`track by`** expression
+- is used, the result of that expression will be set as the value of the `option` and `select` elements.
+-
+-
+- ### `select` **`as`** and **`track by`**
+-
+- <div class="alert alert-warning">
+- Be careful when using `select` **`as`** and **`track by`** in the same expression.
+- </div>
+-
+- Given this array of items on the $scope:
+-
+- ```js
+
+  ```
+
+- $scope.items = [{
+- id: 1,
+- label: 'aLabel',
+- subItem: { name: 'aSubItem' }
+- }, {
+- id: 2,
+- label: 'bLabel',
+- subItem: { name: 'bSubItem' }
+- }];
+- ```
+
+  ```
+
+-
+- This will work:
+-
+- ```html
+
+  ```
+
+- <select ng-options="item as item.label for item in items track by item.id" ng-model="selected"></select>
+- ```
+
+  ```
+
+- ```js
+
+  ```
+
+- $scope.selected = $scope.items[0];
+- ```
+
+  ```
+
+-
+- but this will not work:
+-
+- ```html
+
+  ```
+
+- <select ng-options="item.subItem as item.label for item in items track by item.id" ng-model="selected"></select>
+- ```
+
+  ```
+
+- ```js
+
+  ```
+
+- $scope.selected = $scope.items[0].subItem;
+- ```
+
+  ```
+
+-
+- In both examples, the **`track by`** expression is applied successfully to each `item` in the
+- `items` array. Because the selected option has been set programmatically in the controller, the
+- **`track by`** expression is also applied to the `ngModel` value. In the first example, the
+- `ngModel` value is `items[0]` and the **`track by`** expression evaluates to `items[0].id` with
+- no issue. In the second example, the `ngModel` value is `items[0].subItem` and the **`track by`**
+- expression evaluates to `items[0].subItem.id` (which is undefined). As a result, the model value
+- is not matched against any `<option>` and the `<select>` appears as having no selected value.
+-
+-
+- @param {string} ngModel Assignable AngularJS expression to data-bind to.
+- @param {string} ngOptions in one of the following forms:
+-
+- - for array data sources:
+-     * `label` **`for`** `value` **`in`** `array`
+-     * `select` **`as`** `label` **`for`** `value` **`in`** `array`
+-     * `label` **`group by`** `group` **`for`** `value` **`in`** `array`
+-     * `label` **`disable when`** `disable` **`for`** `value` **`in`** `array`
+-     * `label` **`group by`** `group` **`for`** `value` **`in`** `array` **`track by`** `trackexpr`
+-     * `label` **`disable when`** `disable` **`for`** `value` **`in`** `array` **`track by`** `trackexpr`
+-     * `label` **`for`** `value` **`in`** `array` | orderBy:`orderexpr` **`track by`** `trackexpr`
+-        (for including a filter with `track by`)
+- - for object data sources:
+-     * `label` **`for (`**`key` **`,`** `value`**`) in`** `object`
+-     * `select` **`as`** `label` **`for (`**`key` **`,`** `value`**`) in`** `object`
+-     * `label` **`group by`** `group` **`for (`**`key`**`,`** `value`**`) in`** `object`
+-     * `label` **`disable when`** `disable` **`for (`**`key`**`,`** `value`**`) in`** `object`
+-     * `select` **`as`** `label` **`group by`** `group`
+-         **`for` `(`**`key`**`,`** `value`**`) in`** `object`
+-     * `select` **`as`** `label` **`disable when`** `disable`
+-         **`for` `(`**`key`**`,`** `value`**`) in`** `object`
+-
+- Where:
+-
+- - `array` / `object`: an expression which evaluates to an array / object to iterate over.
+- - `value`: local variable which will refer to each item in the `array` or each property value
+-      of `object` during iteration.
+- - `key`: local variable which will refer to a property name in `object` during iteration.
+- - `label`: The result of this expression will be the label for `<option>` element. The
+-     `expression` will most likely refer to the `value` variable (e.g. `value.propertyName`).
+- - `select`: The result of this expression will be bound to the model of the parent `<select>`
+-      element. If not specified, `select` expression will default to `value`.
+- - `group`: The result of this expression will be used to group options using the `<optgroup>`
+-      DOM element.
+- - `disable`: The result of this expression will be used to disable the rendered `<option>`
+-      element. Return `true` to disable.
+- - `trackexpr`: Used when working with an array of objects. The result of this expression will be
+-      used to identify the objects in the array. The `trackexpr` will most likely refer to the
+-     `value` variable (e.g. `value.propertyName`). With this the selection is preserved
+-      even when the options are recreated (e.g. reloaded from the server).
+- @param {string=} name Property name of the form under which the control is published.
+- @param {string=} required The control is considered valid only if value is entered.
+- @param {string=} ngRequired Adds `required` attribute and `required` validation constraint to
+- the element when the ngRequired expression evaluates to true. Use `ngRequired` instead of
+- `required` when you want to data-bind to the `required` attribute.
+- @param {string=} ngAttrSize sets the size of the select element dynamically. Uses the
+- {@link guide/interpolation#-ngattr-for-binding-to-arbitrary-attributes ngAttr} directive.
+- \*/

package/src/directive/select/select.js

@@ -8,8 +8,6 @@ import {
   shallowCopy,
 } from "../../shared/utils";
 
-const noopNgModelController = { $setViewValue: () => {}, $render: () => {} };
-
 function setOptionSelectedStatus(optionEl, value) {
   optionEl[0].selected = value;
   /**
@@ -29,6 +27,11 @@ function setOptionSelectedStatus(optionEl, value) {
  *
  */
 SelectController.$inject = ["$element", "$scope"];
+/**
+ *
+ * @param {JQLite} $element
+ * @param {import('../../core/scope/scope').Scope} $scope
+ */
 function SelectController($element, $scope) {
   const self = this;
   const optionsMap = new Map();
@@ -36,7 +39,7 @@ function SelectController($element, $scope) {
   self.selectValueMap = {}; // Keys are the hashed values, values the original values
 
   // If the ngModel doesn't get provided then provide a dummy noop version to prevent errors
-  self.ngModelCtrl = noopNgModelController;
+  self.ngModelCtrl = {};
   self.multiple = false;
 
   // The "unknown" option is one that is prepended to the list if the viewValue
@@ -101,7 +104,7 @@ function SelectController($element, $scope) {
 
   // Read the value of the select control, the implementation of this changes depending
   // upon whether the select can have multiple values and whether ngOptions is at work.
-  self.readValue = function readSingleValue() {
+  self.readValue = function () {
     const val = $element.val();
     // ngValue added option values are stored in the selectValueMap, normal interpolations are not
     const realVal = val in self.selectValueMap ? self.selectValueMap[val] : val;

package/src/directive/switch/switch.spec.js

@@ -1,6 +1,6 @@
 import { Angular } from "../../loader";
 import { createInjector } from "../../core/di/injector";
-import { dealoc, JQLite } from "../../shared/jqlite/jqlite";
+import { dealoc } from "../../shared/jqlite/jqlite";
 
 describe("ngSwitch", () => {
   let $scope;

package/src/exts/aria/aria.spec.js

@@ -1,6 +1,6 @@
 import { createInjector } from "../../core/di/injector";
 import { Angular } from "../../loader";
-import { dealoc, JQLite } from "../../shared/jqlite/jqlite";
+import { dealoc } from "../../shared/jqlite/jqlite";
 
 describe("$aria", () => {
   let scope;

package/src/filters/filter.js

@@ -161,9 +161,8 @@ function deepCompare(
 
   switch (actualType) {
     case "object":
-      var key;
       if (matchAgainstAnyProp) {
-        for (key in actual) {
+        for (let key in actual) {
           // Under certain, rare, circumstances, key may not be a string and `charAt` will be undefined
           // See: https://github.com/angular/angular.js/issues/15644
           if (
@@ -179,7 +178,7 @@ function deepCompare(
           : deepCompare(actual, expected, comparator, anyPropertyKey, false);
       }
       if (expectedType === "object") {
-        for (key in expected) {
+        for (let key in expected) {
           const expectedVal = expected[key];
           if (isFunction(expectedVal) || isUndefined(expectedVal)) {
             continue;

package/src/filters/filter.spec.js

@@ -9,7 +9,7 @@ describe("Filter: filter", () => {
   beforeEach(() => {
     window.angular = new Angular();
     window.angular.module("myModule", ["ng"]);
-    var injector = createInjector(["myModule"]);
+    const injector = createInjector(["myModule"]);
     filter = injector.get("$filter")("filter");
   });
 

package/src/filters/filters.spec.js

@@ -8,7 +8,7 @@ describe("filters", () => {
   beforeEach(() => {
     window.angular = new Angular();
     window.angular.module("myModule", ["ng"]);
-    var injector = createInjector(["myModule"]);
+    const injector = createInjector(["myModule"]);
     filter = injector.get("$filter");
   });
 

package/src/filters/limit-to.spec.js

@@ -12,8 +12,8 @@ describe("Filter: limitTo", () => {
   beforeEach(() => {
     window.angular = new Angular();
     window.angular.module("myModule", ["ng"]);
-    var injector = createInjector(["myModule"]);
-    var $filter = injector.get("$filter");
+    const injector = createInjector(["myModule"]);
+    const $filter = injector.get("$filter");
 
     items = ["a", "b", "c", "d", "e", "f", "g", "h"];
     str = "tuvwxyz";

package/src/loader.js

@@ -114,7 +114,7 @@ export class Angular {
     };
 
     this.doBootstrap = function () {
-      var jqLite = JQLite(element);
+      const jqLite = JQLite(element);
 
       if (jqLite.injector()) {
         throw ngMinErr("btstrpd", "App already bootstrapped");

package/src/loader.spec.js

@@ -2,7 +2,7 @@ import { Angular } from "./loader";
 import { createInjector } from "./core/di/injector";
 
 describe("module loader", () => {
-  var angular;
+  let angular;
   beforeEach(() => {
     angular = window.angular = new Angular();
   });

package/src/public.js

@@ -90,7 +90,13 @@ import { TemplateRequestProvider } from "./services/template-request";
 import { $TimeoutProvider } from "./core/timeout/timeout";
 import { SanitizeUriProvider } from "./core/sanitize/sanitize-uri";
 import { initAnimateModule } from "./animations/module";
-import { initMessageModule } from "./exts/messages/messages";
+import {
+  ngMessageDefaultDirective,
+  ngMessageDirective,
+  ngMessageExpDirective,
+  ngMessagesDirective,
+  ngMessagesIncludeDirective,
+} from "./directive/messages/messages";
 import { initAriaModule } from "./exts/aria/aria";
 import { initRouter } from "./router/index";
 
@@ -139,6 +145,11 @@ export function publishExternalAPI(angular) {
               ngIf: ngIfDirective,
               ngInclude: ngIncludeDirective,
               ngInit: ngInitDirective,
+              ngMessages: ngMessagesDirective,
+              ngMessage: ngMessageDirective,
+              ngMessageExp: ngMessageExpDirective,
+              ngMessagesInclude: ngMessagesIncludeDirective,
+              ngMessageDefault: ngMessageDefaultDirective,
               ngNonBindable: ngNonBindableDirective,
               ngRef: ngRefDirective,
               ngRepeat: ngRepeatDirective,
@@ -207,7 +218,6 @@ export function publishExternalAPI(angular) {
     .info({ version: VERSION });
 
   initAnimateModule(angular);
-  initMessageModule(angular);
   initAriaModule(angular);
   initRouter(angular);
   return ng;

package/src/router/common/glob.spec.js

@@ -1,4 +1,4 @@
-import { Glob } from "../../router/common/glob";
+import { Glob } from "./glob";
 
 describe("Glob", function () {
   it("should match exact strings", function () {

package/src/router/params/param-factory.js

@@ -1,4 +1,4 @@
-import { DefType, Param } from "../params/param";
+import { DefType, Param } from "./param";
 
 export class ParamFactory {
   constructor(urlServiceConfig) {

package/src/router/params/param.js

@@ -86,47 +86,6 @@ function getReplace(config, arrayMode, isOptional, squash) {
   ).concat(replace);
 }
 export class Param {
-  static values(params, values = {}) {
-    const paramValues = {};
-    for (const param of params) {
-      paramValues[param.id] = param.value(values[param.id]);
-    }
-    return paramValues;
-  }
-  /**
-   * Finds [[Param]] objects which have different param values
-   *
-   * Filters a list of [[Param]] objects to only those whose parameter values differ in two param value objects
-   *
-   * @param params: The list of Param objects to filter
-   * @param values1: The first set of parameter values
-   * @param values2: the second set of parameter values
-   *
-   * @returns any Param objects whose values were different between values1 and values2
-   */
-  static changed(params, values1 = {}, values2 = {}) {
-    return params.filter(
-      (param) => !param.type.equals(values1[param.id], values2[param.id]),
-    );
-  }
-  /**
-   * Checks if two param value objects are equal (for a set of [[Param]] objects)
-   *
-   * @param params The list of [[Param]] objects to check
-   * @param values1 The first set of param values
-   * @param values2 The second set of param values
-   *
-   * @returns true if the param values in values1 and values2 are equal
-   */
-  static equals(params, values1 = {}, values2 = {}) {
-    return Param.changed(params, values1, values2).length === 0;
-  }
-  /** Returns true if a the parameter values are valid, according to the Param definitions */
-  static validates(params, values = {}) {
-    return params
-      .map((param) => param.validates(values[param.id]))
-      .reduce(allTrueR, true);
-  }
   constructor(id, type, location, urlConfig, state) {
     const config = getParamDeclaration(id, location, state);
     type = getType(config, type, location, id, urlConfig.paramTypes);
@@ -157,20 +116,19 @@ export class Param {
       const arrayParamNomenclature = id.match(/\[\]$/) ? { array: true } : {};
       return Object.assign(arrayDefaults, arrayParamNomenclature, config).array;
     }
-    Object.assign(this, {
-      id,
-      type,
-      location,
-      isOptional,
-      dynamic,
-      raw,
-      squash,
-      replace,
-      inherit,
-      array: arrayMode,
-      config,
-    });
+    this.isOptional = isOptional;
+    this.type = type;
+    this.location = location;
+    this.id = id;
+    this.dynamic = dynamic;
+    this.raw = raw;
+    this.squash = squash;
+    this.replace = replace;
+    this.inherit = inherit;
+    this.array = arrayMode;
+    this.config = config;
   }
+
   isDefaultValue(value) {
     return this.isOptional && this.type.equals(this.value(), value);
   }
@@ -227,4 +185,46 @@ export class Param {
   toString() {
     return `{Param:${this.id} ${this.type} squash: '${this.squash}' optional: ${this.isOptional}}`;
   }
+
+  static values(params, values = {}) {
+    const paramValues = {};
+    for (const param of params) {
+      paramValues[param.id] = param.value(values[param.id]);
+    }
+    return paramValues;
+  }
+  /**
+   * Finds [[Param]] objects which have different param values
+   *
+   * Filters a list of [[Param]] objects to only those whose parameter values differ in two param value objects
+   *
+   * @param params: The list of Param objects to filter
+   * @param values1: The first set of parameter values
+   * @param values2: the second set of parameter values
+   *
+   * @returns any Param objects whose values were different between values1 and values2
+   */
+  static changed(params, values1 = {}, values2 = {}) {
+    return params.filter(
+      (param) => !param.type.equals(values1[param.id], values2[param.id]),
+    );
+  }
+  /**
+   * Checks if two param value objects are equal (for a set of [[Param]] objects)
+   *
+   * @param params The list of [[Param]] objects to check
+   * @param values1 The first set of param values
+   * @param values2 The second set of param values
+   *
+   * @returns true if the param values in values1 and values2 are equal
+   */
+  static equals(params, values1 = {}, values2 = {}) {
+    return Param.changed(params, values1, values2).length === 0;
+  }
+  /** Returns true if a the parameter values are valid, according to the Param definitions */
+  static validates(params, values = {}) {
+    return params
+      .map((param) => param.validates(values[param.id]))
+      .reduce(allTrueR, true);
+  }
 }

package/src/router/path/path-utils.js

@@ -74,6 +74,7 @@ export class PathUtils {
    */
   static inheritParams(fromPath, toPath, toKeys = []) {
     function nodeParamVals(path, state) {
+      /** @type {PathNode} */
       const node = find(path, propEq("state", state));
       return Object.assign({}, node && node.paramValues);
     }

package/src/router/state/state-builder.spec.js

@@ -1,4 +1,4 @@
-import { StateBuilder } from "../../router/state/state-builder";
+import { StateBuilder } from "./state-builder";
 
 // TODO refactor this to url service
 xdescribe("StateBuilder", function () {

package/src/router/template-factory.js

@@ -111,7 +111,9 @@ export class TemplateFactory {
    * string.
    */
   fromString(template, params) {
-    return isFunction(template) ? template(params) : template;
+    return isFunction(template)
+      ? /** @type {Function} */ (template)(params)
+      : template;
   }
   /**
    * Loads a template from the a URL via `$http` and `$templateCache`.
@@ -123,7 +125,7 @@ export class TemplateFactory {
    * for that string.
    */
   fromUrl(url, params) {
-    if (isFunction(url)) url = url(params);
+    if (isFunction(url)) url = /** @type {Function} */ (url)(params);
     if (url == null) return null;
     if (this._useHttp) {
       return this.$http
@@ -141,7 +143,7 @@ export class TemplateFactory {
    * Creates a template by invoking an injectable provider function.
    *
    * @param {import('../types').Injectable<any>} provider Function to invoke via `locals`
-   * @param {Function} injectFn a function used to invoke the template provider
+   * @param {Function} params a function used to invoke the template provider
    * @param {import("./resolve/resolve-context").ResolveContext} context
    * @return {string|Promise.<string>} The template html as a string, or a promise
    * for that string.
@@ -156,7 +158,7 @@ export class TemplateFactory {
    * Creates a component's template by invoking an injectable provider function.
    *
    * @param {import('../types').Injectable<any>} provider Function to invoke via `locals`
-   * @param {Function} injectFn a function used to invoke the template provider
+   * @param {Function} params a function used to invoke the template provider
    * @return {string} The template html as a string: "<component-name input1='::$resolve.foo'></component-name>".
    */
   fromComponentProvider(provider, params, context) {

package/src/router/url/url-service.js

@@ -92,6 +92,13 @@ export class UrlService {
     "$location",
     "$browser",
     "$rootScope",
+    /**
+     *
+     * @param {import('../../core/location/location').Location} $location
+     * @param {import('../../services/browser').Browser} $browser
+     * @param {import('../../core/scope/scope').Scope} $rootScope
+     * @returns
+     */
     ($location, $browser, $rootScope) => {
       this.$location = $location;
       this.$browser = $browser;

package/src/router/view/view.spec.js

@@ -1,16 +1,13 @@
-import { dealoc, JQLite } from "../../shared/jqlite/jqlite";
+import { dealoc } from "../../shared/jqlite/jqlite";
 import { Angular } from "../../loader";
 import { curry } from "../../shared/hof";
-import { StateMatcher } from "../../router/state/state-matcher";
-import { StateBuilder } from "../../router/state/state-builder";
-import { StateObject } from "../../router/state/state-object";
-import { ViewService } from "../../router/view/view";
-import {
-  ng1ViewsBuilder,
-  getNg1ViewConfigFactory,
-} from "../../router/state/views";
-import { PathNode } from "../../router/path/path-node";
-import { PathUtils } from "../../router/path/path-utils";
+import { StateMatcher } from "../state/state-matcher";
+import { StateBuilder } from "../state/state-builder";
+import { StateObject } from "../state/state-object";
+import { ViewService } from "./view.js";
+import { ng1ViewsBuilder, getNg1ViewConfigFactory } from "../state/views.js";
+import { PathNode } from "../path/path-node";
+import { PathUtils } from "../path/path-utils";
 import { tail } from "../../shared/common";
 import { wait } from "../../shared/test-utils";
 

package/src/router/view-scroll.js

@@ -6,7 +6,12 @@ export function $ViewScrollProvider() {
   this.$get = [
     "$anchorScroll",
     "$timeout",
-    function ($anchorScroll, $timeout) {
+    /**
+     * @param {import('../services/anchor-scroll').AnchorScrollObject} $anchorScroll
+     * @param {*} $timeout
+     * @returns {import('../services/anchor-scroll').AnchorScrollObject|Function}
+     */
+    ($anchorScroll, $timeout) => {
       if (useAnchorScroll) {
         return $anchorScroll;
       }