@angular-wave/angular.ts 0.0.67 → 0.0.68

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/exts/messages/messages.js

@@ -20,6 +20,8 @@ export function initMessageModule(angular) {
               const ctrl = this;
               let latestKey = 0;
               let nextAttachId = 0;
+              this.head = undefined;
+              this.default = undefined;
 
               this.getAttachId = function getAttachId() {
                 return nextAttachId++;

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/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/services/anchor-scroll.js

@@ -18,13 +18,11 @@ export function AnchorScrollProvider() {
     "$rootScope",
     /**
      *
-     * @param {*} $location
+     * @param {import('../core/location/location').Location} $location
      * @param {import('../core/scope/scope').Scope} $rootScope
      * @returns
      */
     function ($location, $rootScope) {
-      const { document } = window;
-
       // Helper function to get first anchor from a NodeList
       // (using `Array#some()` instead of `angular#forEach()` since it's more performant
       //  and working in all supported browsers.)
@@ -117,7 +115,7 @@ export function AnchorScrollProvider() {
             if (newVal === oldVal && newVal === "") return;
 
             const action = () => $rootScope.$evalAsync(scroll);
-            if (window.document.readyState === "complete") {
+            if (document.readyState === "complete") {
               // Force the action to be run async for consistent behavior
               // from the action's point of view
               // i.e. it will definitely not be in a $apply

package/src/shared/jqlite/jqlite.js

@@ -522,7 +522,7 @@ JQLite.prototype.append = function (node) {
 };
 
 /**
- * @param {string} node
+ * @param {string|JQLite} node
  * @returns {JQLite}
  */
 JQLite.prototype.prepend = function (node) {

package/types/core/interval/interval-factory.d.ts

@@ -1,4 +1,4 @@
 export function $$IntervalFactoryProvider(): void;
 export class $$IntervalFactoryProvider {
-    $get: (string | (($browser: any, $q: any, $$q: any, $rootScope: any) => (setIntervalFn: any, clearIntervalFn: any) => (fn: any, delay: any, count: any, invokeApply: any, ...args: any[]) => any))[];
+    $get: (string | (($browser: import("../../services/browser").Browser, $q: any, $$q: any, $rootScope: import("../scope/scope").Scope) => (setIntervalFn: any, clearIntervalFn: any) => (fn: any, delay: any, count: any, invokeApply: any, ...args: any[]) => any))[];
 }

package/types/core/interval/interval.d.ts

@@ -2,3 +2,7 @@ export function $IntervalProvider(): void;
 export class $IntervalProvider {
     $get: (string | (($$intervalFactory: any) => any))[];
 }
+/**
+ * Interval ID which uniquely identifies the interval and can be used to cancel it
+ */
+export type IntervalId = number;