@angular/core 12.1.0-next.3 → 12.1.0

package/core.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v12.1.0-next.3
+ * @license Angular v12.1.0
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -411,20 +411,41 @@ export declare class ApplicationRef {
      */
     readonly isStable: Observable<boolean>;
     /**
-     * Bootstrap a new component at the root level of the application.
+     * Bootstrap a component onto the element identified by its selector or, optionally, to a
+     * specified element.
      *
      * @usageNotes
      * ### Bootstrap process
      *
-     * When bootstrapping a new root component into an application, Angular mounts the
-     * specified application component onto DOM elements identified by the componentType's
-     * selector and kicks off automatic change detection to finish initializing the component.
+     * When bootstrapping a component, Angular mounts it onto a target DOM element
+     * and kicks off automatic change detection. The target DOM element can be
+     * provided using the `rootSelectorOrNode` argument.
      *
-     * Optionally, a component can be mounted onto a DOM element that does not match the
-     * componentType's selector.
+     * If the target DOM element is not provided, Angular tries to find one on a page
+     * using the `selector` of the component that is being bootstrapped
+     * (first matched element is used).
      *
      * ### Example
-     * {@example core/ts/platform/platform.ts region='longform'}
+     *
+     * Generally, we define the component to bootstrap in the `bootstrap` array of `NgModule`,
+     * but it requires us to know the component while writing the application code.
+     *
+     * Imagine a situation where we have to wait for an API call to decide about the component to
+     * bootstrap. We can use the `ngDoBootstrap` hook of the `NgModule` and call this method to
+     * dynamically bootstrap a component.
+     *
+     * {@example core/ts/platform/platform.ts region='componentSelector'}
+     *
+     * Optionally, a component can be mounted onto a DOM element that does not match the
+     * selector of the bootstrapped component.
+     *
+     * In the following example, we are providing a CSS selector to match the target element.
+     *
+     * {@example core/ts/platform/platform.ts region='cssSelector'}
+     *
+     * While in this example, we are providing reference to a DOM node.
+     *
+     * {@example core/ts/platform/platform.ts region='domNode'}
      */
     bootstrap<C>(componentOrFactory: ComponentFactory<C> | Type<C>, rootSelectorOrNode?: string | any): ComponentRef<C>;
     /**
@@ -1153,6 +1174,9 @@ export { ComponentFactory as ɵComponentFactory }
  * then use the factory's `create()` method to create a component of that type.
  *
  * @see [Dynamic Components](guide/dynamic-component-loader)
+ * @see [Usage Example](guide/dynamic-component-loader#resolving-components)
+ * @see <live-example name="dynamic-component-loader" noDownload></live-example>
+of the code in this cookbook
  * @publicApi
  */
 export declare abstract class ComponentFactoryResolver {
@@ -1318,6 +1342,24 @@ export declare interface ContentChildDecorator {
      * * **static** - True to resolve query results before change detection runs,
      * false to resolve after change detection. Defaults to false.
      *
+     * The following selectors are supported.
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * A template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
+     * with `@ContentChild('cmp')`)
+     *   * Any provider defined in the child component tree of the current component (e.g.
+     * `@ContentChild(SomeService) someService: SomeService`)
+     *   * Any provider defined through a string token (e.g. `@ContentChild('someToken') someTokenVal:
+     * any`)
+     *   * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ContentChild(TemplateRef)
+     * template;`)
+     *
+     * The following values are supported by `read`:
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * Any provider defined on the injector of the component that is matched by the `selector` of
+     * this query
+     *   * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`)
+     *   * `TemplateRef`, `ElementRef`, and `ViewContainerRef`
+     *
      * @usageNotes
      *
      * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
@@ -1387,6 +1429,27 @@ export declare interface ContentChildrenDecorator {
      *   removed in future versions of Angular.
      * * **read** - Used to read a different token from the queried elements.
      *
+     * The following selectors are supported.
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * A template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
+     * with `@ContentChildren('cmp')`)
+     *   * Any provider defined in the child component tree of the current component (e.g.
+     * `@ContentChildren(SomeService) someService: SomeService`)
+     *   * Any provider defined through a string token (e.g. `@ContentChildren('someToken')
+     * someTokenVal: any`)
+     *   * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with
+     * `@ContentChildren(TemplateRef) template;`)
+     *
+     * In addition, multiple string selectors can be separated with a comma (e.g.
+     * `@ContentChildren('cmp1,cmp2')`)
+     *
+     * The following values are supported by `read`:
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * Any provider defined on the injector of the component that is matched by the `selector` of
+     * this query
+     *   * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`)
+     *   * `TemplateRef`, `ElementRef`, and `ViewContainerRef`
+     *
      * @usageNotes
      *
      * Here is a simple demonstration of how the `ContentChildren` decorator can be used.
@@ -1560,27 +1623,98 @@ export declare const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata;
 
 /**
  * @publicApi
+ *
+ * @see [Component testing scenarios](guide/testing-components-scenarios)
+ * @see [Basics of testing components](guide/testing-components-basics)
+ * @see [Testing utility APIs](guide/testing-utility-apis)
  */
 export declare interface DebugElement extends DebugNode {
+    /**
+     * The element tag name, if it is an element.
+     */
     readonly name: string;
+    /**
+     *  A map of property names to property values for an element.
+     *
+     *  This map includes:
+     *  - Regular property bindings (e.g. `[id]="id"`)
+     *  - Host property bindings (e.g. `host: { '[id]': "id" }`)
+     *  - Interpolated property bindings (e.g. `id="{{ value }}")
+     *
+     *  It does not include:
+     *  - input property bindings (e.g. `[myCustomInput]="value"`)
+     *  - attribute bindings (e.g. `[attr.role]="menu"`)
+     */
     readonly properties: {
         [key: string]: any;
     };
+    /**
+     *  A map of attribute names to attribute values for an element.
+     */
     readonly attributes: {
         [key: string]: string | null;
     };
+    /**
+     * A map containing the class names on the element as keys.
+     *
+     * This map is derived from the `className` property of the DOM element.
+     *
+     * Note: The values of this object will always be `true`. The class key will not appear in the KV
+     * object if it does not exist on the element.
+     *
+     * @see [Element.className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className)
+     */
     readonly classes: {
         [key: string]: boolean;
     };
+    /**
+     * The inline styles of the DOM element.
+     *
+     * Will be `null` if there is no `style` property on the underlying DOM element.
+     *
+     * @see [ElementCSSInlineStyle](https://developer.mozilla.org/en-US/docs/Web/API/ElementCSSInlineStyle/style)
+     */
     readonly styles: {
         [key: string]: string | null;
     };
+    /**
+     * The `childNodes` of the DOM element as a `DebugNode` array.
+     *
+     * @see [Node.childNodes](https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes)
+     */
     readonly childNodes: DebugNode[];
+    /**
+     * The underlying DOM element at the root of the component.
+     */
     readonly nativeElement: any;
+    /**
+     * The immediate `DebugElement` children. Walk the tree by descending through `children`.
+     */
     readonly children: DebugElement[];
+    /**
+     * @returns the first `DebugElement` that matches the predicate at any depth in the subtree.
+     */
     query(predicate: Predicate<DebugElement>): DebugElement;
+    /**
+     * @returns All `DebugElement` matches for the predicate at any depth in the subtree.
+     */
     queryAll(predicate: Predicate<DebugElement>): DebugElement[];
+    /**
+     * @returns All `DebugNode` matches for the predicate at any depth in the subtree.
+     */
     queryAllNodes(predicate: Predicate<DebugNode>): DebugNode[];
+    /**
+     * Triggers the event by its name if there is a corresponding listener in the element's
+     * `listeners` collection.
+     *
+     * If the event lacks a listener or there's some other problem, consider
+     * calling `nativeElement.dispatchEvent(eventObject)`.
+     *
+     * @param eventName The name of the event to trigger
+     * @param eventObj The _event object_ expected by the handler
+     *
+     * @see [Testing components scenarios](guide/testing-components-scenarios#trigger-event-handler)
+     */
     triggerEventHandler(eventName: string, eventObj: any): void;
 }
 
@@ -1640,15 +1774,47 @@ export declare class DebugEventListener {
  * @publicApi
  */
 export declare interface DebugNode {
+    /**
+     * The callbacks attached to the component's @Output properties and/or the element's event
+     * properties.
+     */
     readonly listeners: DebugEventListener[];
+    /**
+     * The `DebugElement` parent. Will be `null` if this is the root element.
+     */
     readonly parent: DebugElement | null;
+    /**
+     * The underlying DOM node.
+     */
     readonly nativeNode: any;
+    /**
+     * The host dependency injector. For example, the root element's component instance injector.
+     */
     readonly injector: Injector;
+    /**
+     * The element's own component instance, if it has one.
+     */
     readonly componentInstance: any;
+    /**
+     * An object that provides parent context for this element. Often an ancestor component instance
+     * that governs this element.
+     *
+     * When an element is repeated within *ngFor, the context is an `NgForOf` whose `$implicit`
+     * property is the value of the row instance value. For example, the `hero` in `*ngFor="let hero
+     * of heroes"`.
+     */
     readonly context: any;
+    /**
+     * Dictionary of objects associated with template local variables (e.g. #foo), keyed by the local
+     * variable name.
+     */
     readonly references: {
         [key: string]: any;
     };
+    /**
+     * This component's injector lookup tokens. Includes the component itself plus the tokens that the
+     * component lists in its providers metadata.
+     */
     readonly providerTokens: any[];
 }
 
@@ -2162,14 +2328,17 @@ declare interface DisposableFn {
 
 /**
  * @description
- * Hook for manual bootstrapping of the application instead of using bootstrap array in @NgModule
- * annotation.
+ * Hook for manual bootstrapping of the application instead of using `bootstrap` array in @NgModule
+ * annotation. This hook is invoked only when the `bootstrap` array is empty or not provided.
  *
  * Reference to the current application is provided as a parameter.
  *
  * See ["Bootstrapping"](guide/bootstrapping) and ["Entry components"](guide/entry-components).
  *
  * @usageNotes
+ * The example below uses `ApplicationRef.bootstrap()` to render the
+ * `AppComponent` on the page.
+ *
  * ```typescript
  * class AppModule implements DoBootstrap {
  *   ngDoBootstrap(appRef: ApplicationRef) {
@@ -3256,9 +3425,15 @@ export declare const inject: typeof ɵɵinject;
  */
 export declare interface Injectable {
     /**
-     * Determines which injectors will provide the injectable,
-     * by either associating it with an `@NgModule` or other `InjectorType`,
-     * or by specifying that this injectable should be provided in one of the following injectors:
+     * Determines which injectors will provide the injectable.
+     *
+     * - `Type<any>` - associates the injectable with an `@NgModule` or other `InjectorType`,
+     * - 'null' : Equivalent to `undefined`. The injectable is not provided in any scope automatically
+     * and must be added to a `providers` array of an [@NgModule](api/core/NgModule#providers),
+     * [@Component](api/core/Directive#providers) or [@Directive](api/core/Directive#providers).
+     *
+     * The following options specify that this injectable should be provided in one of the following
+     * injectors:
      * - 'root' : The application-level injector in most apps.
      * - 'platform' : A special singleton platform injector shared by all
      * applications on the page.
@@ -4507,7 +4682,10 @@ export declare interface NgModule {
      * using one of the imperative techniques, such as `ViewContainerRef.createComponent()`.
      *
      * @see [Entry Components](guide/entry-components)
-     * @deprecated Since 9.0.0. With Ivy, this property is no longer necessary.
+     * @deprecated
+     * Since 9.0.0. With Ivy, this property is no longer necessary.
+     * (You may need to keep these if building a library that will be consumed by a View Engine
+     * application.)
      */
     entryComponents?: Array<Type<any> | any[]>;
     /**
@@ -4800,6 +4978,10 @@ export declare class NgZone {
 /**
  * Defines a schema that allows any property on any element.
  *
+ * This schema allows you to ignore the errors related to any unknown elements or properties in a
+ * template. The usage of this schema is generally discouraged because it prevents useful validation
+ * and may hide real errors in your template. Consider using the `CUSTOM_ELEMENTS_SCHEMA` instead.
+ *
  * @publicApi
  */
 export declare const NO_ERRORS_SCHEMA: SchemaMetadata;
@@ -7837,15 +8019,55 @@ declare interface TQueryMetadata {
 }
 
 /**
- * An optional function passed into the `NgForOf` directive that defines how to track
- * changes for items in an iterable.
- * The function takes the iteration index and item ID.
- * When supplied, Angular tracks changes by the return value of the function.
+ * A function optionally passed into the `NgForOf` directive to customize how `NgForOf` uniquely
+ * identifies items in an iterable.
+ *
+ * `NgForOf` needs to uniquely identify items in the iterable to correctly perform DOM updates
+ * when items in the iterable are reordered, new items are added, or existing items are removed.
+ *
+ *
+ * In all of these scenarios it is usually desirable to only update the DOM elements associated
+ * with the items affected by the change. This behavior is important to:
+ *
+ * - preserve any DOM-specific UI state (like cursor position, focus, text selection) when the
+ *   iterable is modified
+ * - enable animation of item addition, removal, and iterable reordering
+ * - preserve the value of the `<select>` element when nested `<option>` elements are dynamically
+ *   populated using `NgForOf` and the bound iterable is updated
+ *
+ * A common use for custom `trackBy` functions is when the model that `NgForOf` iterates over
+ * contains a property with a unique identifier. For example, given a model:
+ *
+ * ```ts
+ * class User {
+ *   id: number;
+ *   name: string;
+ *   ...
+ * }
+ * ```
+ * a custom `trackBy` function could look like the following:
+ * ```ts
+ * function userTrackBy(index, user) {
+ *   return user.id;
+ * }
+ * ```
+ *
+ * A custom `trackBy` function must have several properties:
  *
+ * - be [idempotent](https://en.wikipedia.org/wiki/Idempotence) (be without side effects, and always
+ * return the same value for a given input)
+ * - return unique value for all unique inputs
+ * - be fast
+ *
+ * @see [`NgForOf#ngForTrackBy`](api/common/NgForOf#ngForTrackBy)
  * @publicApi
  */
 export declare interface TrackByFunction<T> {
-    (index: number, item: T): any;
+    /**
+     * @param index The index of the item within the iterable.
+     * @param item The item in the iterable.
+     */
+    <U extends T>(index: number, item: U): any;
 }
 
 /**
@@ -8488,6 +8710,13 @@ export declare interface ViewChildDecorator {
      *   * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ViewChild(TemplateRef)
      * template;`)
      *
+     * The following values are supported by `read`:
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * Any provider defined on the injector of the component that is matched by the `selector` of
+     * this query
+     *   * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`)
+     *   * `TemplateRef`, `ElementRef`, and `ViewContainerRef`
+     *
      * @usageNotes
      *
      * {@example core/di/ts/viewChild/view_child_example.ts region='Component'}
@@ -8550,6 +8779,27 @@ export declare interface ViewChildrenDecorator {
      *   ** Note: *** This config option is **deprecated**, it will be permanently set to `true` and
      * removed in future versions of Angular.
      *
+     * The following selectors are supported.
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * A template reference variable as a string (e.g. query `<my-component #cmp></my-component>`
+     * with `@ViewChildren('cmp')`)
+     *   * Any provider defined in the child component tree of the current component (e.g.
+     * `@ViewChildren(SomeService) someService: SomeService`)
+     *   * Any provider defined through a string token (e.g. `@ViewChildren('someToken') someTokenVal:
+     * any`)
+     *   * A `TemplateRef` (e.g. query `<ng-template></ng-template>` with `@ViewChildren(TemplateRef)
+     * template;`)
+     *
+     * In addition, multiple string selectors can be separated with a comma (e.g.
+     * `@ViewChildren('cmp1,cmp2')`)
+     *
+     * The following values are supported by `read`:
+     *   * Any class with the `@Component` or `@Directive` decorator
+     *   * Any provider defined on the injector of the component that is matched by the `selector` of
+     * this query
+     *   * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`)
+     *   * `TemplateRef`, `ElementRef`, and `ViewContainerRef`
+     *
      * @usageNotes
      *
      * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}