@angular/core 6.0.3 → 6.0.7

package/src/metadata/directives.d.ts

@@ -12,25 +12,9 @@ import { TypeDecorator } from '../util/decorators';
 import { ViewEncapsulation } from './view';
 /**
  * Type of the Directive decorator / constructor function.
- *
- *
  */
 export interface DirectiveDecorator {
     /**
-     * @usageNotes
-     *
-     * ```
-     * import {Directive} from '@angular/core';
-     *
-     * @Directive({
-     *   selector: 'my-directive',
-     * })
-     * export class MyDirective {
-     * }
-     * ```
-     *
-     * @description
-     *
      * Marks a class as an Angular directive and collects directive configuration
      * metadata.
      *
@@ -61,12 +45,23 @@ export interface DirectiveDecorator {
      * * **queries** -  configure queries that can be injected into the component
      * * **selector** - css selector that identifies this component in a template
      *
+     * @usageNotes
+     *
+     * ```
+     * import {Directive} from '@angular/core';
+     *
+     * @Directive({
+     *   selector: 'my-directive',
+     * })
+     * export class MyDirective {
+     * }
+     * ```
      *
      * @Annotation
      */
     (obj: Directive): TypeDecorator;
     /**
-     * See the {@link Directive} decorator.
+     * See the `Directive` decorator.
      */
     new (obj: Directive): Directive;
 }
@@ -86,7 +81,7 @@ export interface Directive {
      * - `:not(sub_selector)`: select only if the element does not match the `sub_selector`.
      * - `selector1, selector2`: select if either `selector1` or `selector2` matches.
      *
-     *
+     * @usageNotes
      * ### Example
      *
      * Suppose we have a directive with an `input[type=text]` selector.
@@ -117,7 +112,8 @@ export interface Directive {
      *
      * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`.
      *
-     * ### Example ([live demo](http://plnkr.co/edit/ivhfXY?p=preview))
+     * @usageNotes
+     * ### Example
      *
      * The following example creates a component with two data-bound properties.
      *
@@ -134,19 +130,7 @@ export interface Directive {
      *   bankName: string;
      *   id: string;
      *
-     *   // this property is not bound, and won't be automatically updated by Angular
-     *   normalizedBankName: string;
-     * }
-     *
-     * @Component({
-     *   selector: 'app',
-     *   template: `
-     *     <bank-account bankName="RBC" account-id="4747"></bank-account>
-     *   `
-     * })
-     * class App {}
      * ```
-     *
      */
     inputs?: string[];
     /**
@@ -161,42 +145,34 @@ export interface Directive {
      * - `directiveProperty` specifies the component property that emits events.
      * - `bindingProperty` specifies the DOM property the event handler is attached to.
      *
-     * ### Example ([live demo](http://plnkr.co/edit/d5CNq7?p=preview))
+     * @usageNotes
+     * ### Example
      *
      * ```typescript
      * @Directive({
-     *   selector: 'interval-dir',
-     *   outputs: ['everySecond', 'five5Secs: everyFiveSeconds']
+     *   selector: 'child-dir',
+     *   exportAs: 'child'
      * })
-     * class IntervalDir {
-     *   everySecond = new EventEmitter();
-     *   five5Secs = new EventEmitter();
-     *
-     *   constructor() {
-     *     setInterval(() => this.everySecond.emit("event"), 1000);
-     *     setInterval(() => this.five5Secs.emit("event"), 5000);
-     *   }
+     * class ChildDir {
      * }
      *
      * @Component({
-     *   selector: 'app',
-     *   template: `
-     *     <interval-dir (everySecond)="everySecond()" (everyFiveSeconds)="everyFiveSeconds()">
-     *     </interval-dir>
-     *   `
+     *   selector: 'main',
+     *   template: `<child-dir #c="child"></child-dir>`
      * })
-     * class App {
-     *   everySecond() { console.log('second'); }
-     *   everyFiveSeconds() { console.log('five seconds'); }
+     * class MainComponent {
      * }
      * ```
-     *
      */
     outputs?: string[];
     /**
      * Specify the events, actions, properties and attributes related to the host element.
      *
-     * ## Host Listeners
+     * @usageNotes
+     * The key corresponds to the name of the event, property or attribute on the host to
+     * bind. The value is formatted differently depending upon the type of the binding.
+     *
+     * ### Host Listeners
      *
      * Specifies which DOM events a directive listens to via a set of `(event)` to `method`
      * key-value pairs:
@@ -211,8 +187,6 @@ export interface Directive {
      *
      * When writing a directive event binding, you can also refer to the $event local variable.
      *
-     * ### Example ([live demo](http://plnkr.co/edit/DlA5KU?p=preview))
-     *
      * The following example declares a directive that attaches a click listener to the button and
      * counts clicks.
      *
@@ -237,16 +211,15 @@ export interface Directive {
      * })
      * class App {}
      * ```
+     * See [live demo](http://plnkr.co/edit/DlA5KU?p=preview)
      *
-     * ## Host Property Bindings
+     * ### Host Property Bindings
      *
      * Specifies which DOM properties a directive updates.
      *
      * Angular automatically checks host property bindings during change detection.
      * If a binding changes, it will update the host element of the directive.
      *
-     * ### Example ([live demo](http://plnkr.co/edit/gNg0ED?p=preview))
-     *
      * The following example creates a directive that sets the `valid` and `invalid` classes
      * on the DOM element that has ngModel directive on it.
      *
@@ -272,13 +245,12 @@ export interface Directive {
      *   prop;
      * }
      * ```
+     * See [live demo](http://plnkr.co/edit/gNg0ED?p=preview).
      *
-     * ## Attributes
+     * ### Attributes
      *
      * Specifies static attributes that should be propagated to a host element.
      *
-     * ### Example
-     *
      * In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
      * (here: `<div>` ) will ensure that this element will get the "button" role.
      *
@@ -292,17 +264,18 @@ export interface Directive {
      * class MyButton {
      * }
      * ```
-     */
-    host?: {
-        [key: string]: string;
-    };
-    /**
-     * Defines the set of injectable objects that are visible to a Directive and its light DOM
-     * children.
+     * Attaching the `my-button` directive to the host `<div>` element
+     * ensures that this element gets the "button" role.
+     *
+     * ```html
+     * <div my-button></div>
+     * ```
      *
-     * ## Simple Example
+     * @usageNotes
+     * ### Simple Example
      *
-     * Here is an example of a class that can be injected:
+     * The following simple example shows how a class is injected,
+     * using a provider specified in the directive metadata:
      *
      * ```
      * class Greeter {
@@ -330,7 +303,8 @@ export interface Directive {
     /**
      * Defines the name that can be used in the template to assign this directive to a variable.
      *
-     * ## Simple Example
+     * @usageNotes
+     * ### Simple Example
      *
      * ```
      * @Directive({
@@ -356,8 +330,10 @@ export interface Directive {
      * Content queries are set before the `ngAfterContentInit` callback is called.
      * View queries are set before the `ngAfterViewInit` callback is called.
      *
+     * @usageNotes
      * ### Example
      *
+     * The followoing example (shows what??)
      * ```
      * @Component({
      *   selector: 'someDir',
@@ -380,6 +356,8 @@ export interface Directive {
      *   }
      * }
      * ```
+     *
+     * @Annotation
      */
     queries?: {
         [key: string]: any;
@@ -388,100 +366,145 @@ export interface Directive {
 /**
  * Directive decorator and metadata.
  *
- *
  * @Annotation
  */
-export declare const Directive: DirectiveDecorator;
-/**
- * Type of the Component decorator / constructor function.
- *
- *
- */
-export interface ComponentDecorator {
+export interface Directive {
     /**
-     * @usageNotes
+     * The CSS selector that identifies this directive in a template
+     * and triggers instantiation of the directive.
      *
-     * {@example core/ts/metadata/metadata.ts region='component'}
+     * Declare as one of the following:
      *
-     * @description
-     * Marks a class as an Angular component and collects component configuration
-     * metadata.
+     * - `element-name`: Select by element name.
+     * - `.class`: Select by class name.
+     * - `[attribute]`: Select by attribute name.
+     * - `[attribute=value]`: Select by attribute name and value.
+     * - `:not(sub_selector)`: Select only if the element does not match the `sub_selector`.
+     * - `selector1, selector2`: Select if either `selector1` or `selector2` matches.
      *
-     * Component decorator allows you to mark a class as an Angular component and provide additional
-     * metadata that determines how the component should be processed, instantiated and used at
-     * runtime.
+     * Angular only allows directives to apply on CSS selectors that do not cross
+     * element boundaries.
      *
-     * Components are the most basic building block of an UI in an Angular application.
-     * An Angular application is a tree of Angular components.
-     * Angular components are a subset of directives. Unlike directives, components always have
-     * a template and only one component can be instantiated per an element in a template.
+     * For the following template HTML, a directive with an `input[type=text]` selector,
+     * would be instantiated only on the `<input type="text">` element.
      *
-     * A component must belong to an NgModule in order for it to be usable
-     * by another component or application. To specify that a component is a member of an NgModule,
-     * you should list it in the `declarations` field of that NgModule.
+     * ```html
+     * <form>
+     *   <input type="text">
+     *   <input type="radio">
+     * <form>
+     * ```
      *
-     * In addition to the metadata configuration specified via the Component decorator,
-     * components can control their runtime behavior by implementing various Life-Cycle hooks.
+     */
+    selector?: string;
+    /**
+     * The set of event-bound output properties.
+     * When an output property emits an event, an event handler attached
+     * to that event in the template is invoked.
      *
-     * **Metadata Properties:**
+     * Each output property maps a `directiveProperty` to a `bindingProperty`:
+     * - `directiveProperty` specifies the component property that emits events.
+     * - `bindingProperty` specifies the HTML attribute the event handler is attached to.
      *
-     * * **animations** - list of animations of this component
-     * * **changeDetection** - change detection strategy used by this component
-     * * **encapsulation** - style encapsulation strategy used by this component
-     * * **entryComponents** - list of components that are dynamically inserted into the view of this
-     *   component
-     * * **exportAs** - name under which the component instance is exported in a template
-     * * **host** - map of class property to host element bindings for events, properties and
-     *   attributes
-     * * **inputs** - list of class property names to data-bind as component inputs
-     * * **interpolation** - custom interpolation markers used in this component's template
-     * * **moduleId** - ES/CommonJS module id of the file in which this component is defined
-     * * **outputs** - list of class property names that expose output events that others can
-     *   subscribe to
-     * * **providers** - list of providers available to this component and its children
-     * * **queries** -  configure queries that can be injected into the component
-     * * **selector** - css selector that identifies this component in a template
-     * * **styleUrls** - list of urls to stylesheets to be applied to this component's view
-     * * **styles** - inline-defined styles to be applied to this component's view
-     * * **template** - inline-defined template for the view
-     * * **templateUrl** - url to an external file containing a template for the view
-     * * **viewProviders** - list of providers available to this component and its view children
+     */
+    outputs?: string[];
+    /**
+     * Maps class properties to host element bindings for properties,
+     * attributes, and events, using a set of key-value pairs.
      *
-     * ### Example
+     * Angular automatically checks host property bindings during change detection.
+     * If a binding changes, Angular updates the directive's host element.
      *
-     * {@example core/ts/metadata/metadata.ts region='component'}
+     * When the key is a property of the host element, the property value is
+     * the propagated to the specified DOM property.
      *
+     * When the key is a static attribute in the DOM, the attribute value
+     * is propagated to the specified property in the host element.
+     *
+     * For event handling:
+     * - The key is the DOM event that the directive listens to.
+     * To listen to global events, add the target to the event name.
+     * The target can be `window`, `document` or `body`.
+     * - The value is the statement to execute when the event occurs. If the
+     * statement evalueates to `false`, then `preventDefault` is applied on the DOM
+     * event. A handler method can refer to the `$event` local variable.
      *
-     * @Annotation
      */
-    (obj: Component): TypeDecorator;
+    host?: {
+        [key: string]: string;
+    };
     /**
-     * See the {@link Component} decorator.
+     * See the `Component` decorator.
      */
-    new (obj: Component): Component;
+    providers?: Provider[];
+    /**
+     * The name or names that can be used in the template to assign this directive to a variable.
+     * For multiple names, use a comma-separated string.
+     *
+     */
+    exportAs?: string;
+    /**
+     * Configures the queries that will be injected into the directive.
+     *
+     * Content queries are set before the `ngAfterContentInit` callback is called.
+     * View queries are set before the `ngAfterViewInit` callback is called.
+     *
+     */
+    queries?: {
+        [key: string]: any;
+    };
 }
 /**
  * Type of the Component metadata.
- *
+ */
+export declare const Directive: DirectiveDecorator;
+/**
+ * Component decorator interface
  *
  */
-export interface Component extends Directive {
+export interface ComponentDecorator {
     /**
-     * Defines the used change detection strategy.
+     * Decorator that marks a class as an Angular component and provides configuration
+     * metadata that determines how the component should be processed,
+     * instantiated, and used at runtime.
      *
-     * When a component is instantiated, Angular creates a change detector, which is responsible for
-     * propagating the component's bindings.
+     * Components are the most basic UI building block of an Angular app.
+     * An Angular app contains a tree of Angular components.
      *
-     * The `changeDetection` property defines, whether the change detection will be checked every time
-     * or only when the component tells it to do so.
-     */
-    changeDetection?: ChangeDetectionStrategy;
-    /**
-     * Defines the set of injectable objects that are visible to its view DOM children.
+     * Angular components are a subset of directives, always associated with a template.
+     * Unlike other directives, only one component can be instantiated per an element in a template.
+     *
+     * A component must belong to an NgModule in order for it to be available
+     * to another component or application. To make it a member of an NgModule,
+     * list it in the `declarations` field of the `@NgModule` metadata.
+     *
+     * Note that, in addition to these options for configuring a directive,
+     * you can control a component's runtime behavior by implementing
+     * life-cycle hooks. For more information, see the
+     * [Lifecycle Hooks](guide/lifecycle-hooks) guide.
+     *
+     * @usageNotes
      *
-     * ## Simple Example
+     * ### Setting component inputs
      *
-     * Here is an example of a class that can be injected:
+     * The following example creates a component with two data-bound properties,
+     * specified by the `inputs` value.
+     *
+     * <code-example path="core/ts/metadata/directives.ts" region="component-input">
+     * </code-example>
+     *
+     *
+     * ### Setting component outputs
+     *
+     * The following example shows two event emitters that emit on an interval. One
+     * emits an output every second, while the other emits every five seconds.
+     *
+     * {@example core/ts/metadata/directives.ts region='component-output-interval'}
+     *
+     * ### Injecting a class with a view provider
+     *
+     * The following simple example injects a class into a component
+     * using the view provider specified in component metadata:
      *
      * ```
      * class Greeter {
@@ -512,312 +535,300 @@ export interface Component extends Directive {
      * }
      *
      * ```
+     *
+     *
+     * @Annotation
      */
-    viewProviders?: Provider[];
+    (obj: Component): TypeDecorator;
     /**
-     * The module id of the module that contains the component.
-     * Needed to be able to resolve relative urls for templates and styles.
-     * In CommonJS, this can always be set to `module.id`, similarly SystemJS exposes `__moduleName`
-     * variable within each module.
-     *
+     * See the `@Component` decorator.
+     */
+    new (obj: Component): Component;
+}
+/**
+ * Supplies configuration metadata for an Angular component.
+ */
+export interface Component extends Directive {
+    /**
+     * The change-detection strategy to use for this component.
      *
-     * ## Simple Example
+     * When a component is instantiated, Angular creates a change detector,
+     * which is responsible for propagating the component's bindings.
+     * The strategy is one of:
+     * - `ChangeDetectionStrategy#OnPush` sets the strategy to `CheckOnce` (on demand).
+     * - `ChangeDetectionStrategy#Default` sets the strategy to `CheckAlways`.
+     */
+    changeDetection?: ChangeDetectionStrategy;
+    /**
+     * Defines the set of injectable objects that are visible to its view DOM children.
+     * See [example](#injecting-a-class-with-a-view-provider).
      *
-     * ```
-     * @Directive({
-     *   selector: 'someDir',
-     *   moduleId: module.id
-     * })
-     * class SomeDir {
-     * }
+     */
+    viewProviders?: Provider[];
+    /**
+     * The module ID of the module that contains the component.
+     * The component must be able to resolve relative URLs for templates and styles.
+     * SystemJS exposes the `__moduleName` variable within each module.
+     * In CommonJS, this can  be set to `module.id`.
      *
-     * ```
      */
     moduleId?: string;
     /**
-     * Specifies a template URL for an Angular component.
+     * The URL of a template file for an Angular component. If provided,
+     * do not supply an inline template using `template`.
      *
-     *Only one of `templateUrl` or `template` can be defined per View.
      */
     templateUrl?: string;
     /**
-     * Specifies an inline template for an Angular component.
+     * An inline template for an Angular component. If provided,
+     * do not supply a template file using `templateUrl`.
      *
-     * Only one of `templateUrl` or `template` can be defined per Component.
      */
     template?: string;
     /**
-     * Specifies stylesheet URLs for an Angular component.
+     * One or more URLs for files containing CSS stylesheets to use
+     * in this component.
      */
     styleUrls?: string[];
     /**
-     * Specifies inline stylesheets for an Angular component.
+     * One or more inline CSS stylesheets to use
+     * in this component.
      */
     styles?: string[];
     /**
-     * Animations are defined on components via an animation-like DSL. This DSL approach to describing
-     * animations allows for a flexibility that both benefits developers and the framework.
-     *
-     * Animations work by listening on state changes that occur on an element within
-     * the template. When a state change occurs, Angular can then take advantage and animate the
-     * arc in between. This works similar to how CSS transitions work, however, by having a
-     * programmatic DSL, animations are not limited to environments that are DOM-specific.
-     * (Angular can also perform optimizations behind the scenes to make animations more performant.)
-     *
-     * For animations to be available for use, animation state changes are placed within
-     * {@link trigger animation triggers} which are housed inside of the `animations` annotation
-     * metadata. Within a trigger both {@link state state} and {@link transition transition} entries
-     * can be placed.
-     *
-     * ```typescript
-     * @Component({
-     *   selector: 'animation-cmp',
-     *   templateUrl: 'animation-cmp.html',
-     *   animations: [
-     *     // this here is our animation trigger that
-     *     // will contain our state change animations.
-     *     trigger('myTriggerName', [
-     *       // the styles defined for the `on` and `off`
-     *       // states declared below are persisted on the
-     *       // element once the animation completes.
-     *       state('on', style({ opacity: 1 }),
-     *       state('off', style({ opacity: 0 }),
-     *
-     *       // this here is our animation that kicks off when
-     *       // this state change jump is true
-     *       transition('on => off', [
-     *         animate("1s")
-     *       ])
-     *     ])
-     *   ]
-     * })
-     * ```
-     *
-     * As depicted in the code above, a group of related animation states are all contained within
-     * an animation `trigger` (the code example above called the trigger `myTriggerName`).
-     * When a trigger is created then it can be bound onto an element within the component's
-     * template via a property prefixed by an `@` symbol followed by trigger name and an expression
-     * that
-     * is used to determine the state value for that trigger.
-     *
-     * ```html
-     * <!-- animation-cmp.html -->
-     * <div @myTriggerName="expression">...</div>
-     * ```
+     * One or more animation `trigger()` calls, containing
+     * `state()` and `transition()` definitions.
+     * See the [Animations guide](/guide/animations) and animations API documentation.
      *
-     * For state changes to be executed, the `expression` value must change value from its existing
-     * value
-     * to something that we have set an animation to animate on (in the example above we are listening
-     * to a change of state between `on` and `off`). The `expression` value attached to the trigger
-     * must be something that can be evaluated with the template/component context.
-     *
-     * ### DSL Animation Functions
-     *
-     * Please visit each of the animation DSL functions listed below to gain a better understanding
-     * of how and why they are used for crafting animations in Angular:
-     *
-     * - {@link trigger trigger()}
-     * - {@link state state()}
-     * - {@link transition transition()}
-     * - {@link group group()}
-     * - {@link sequence sequence()}
-     * - {@link style style()}
-     * - {@link animate animate()}
-     * - {@link keyframes keyframes()}
      */
     animations?: any[];
     /**
-     * Specifies how the template and the styles should be encapsulated:
-     * - {@link ViewEncapsulation#Native `ViewEncapsulation.Native`} to use shadow roots - only works
-     *   if natively available on the platform,
-     * - {@link ViewEncapsulation#Emulated `ViewEncapsulation.Emulated`} to use shimmed CSS that
-     *   emulates the native behavior,
-     * - {@link ViewEncapsulation#None `ViewEncapsulation.None`} to use global CSS without any
-     *   encapsulation.
-     *
-     * When no `encapsulation` is defined for the component, the default value from the
-     * {@link CompilerOptions} is used. The default is `ViewEncapsulation.Emulated`}. Provide a new
-     * `CompilerOptions` to override this value.
-     *
-     * If the encapsulation is set to `ViewEncapsulation.Emulated` and the component has no `styles`
-     * nor `styleUrls` the encapsulation will automatically be switched to `ViewEncapsulation.None`.
+     * An encapsulation policy for the template and CSS styles. One of:
+     * - `ViewEncapsulation.Native`: Use shadow roots. This works
+     * only if natively available on the platform.
+     * - `ViewEncapsulation.Emulated`: Use shimmed CSS that
+     * emulates the native behavior.
+     * - `ViewEncapsulation.None`: Use global CSS without any
+     * encapsulation.
+     *
+     * If not supplied, the value is taken from `CompilerOptions`. The default compiler option is
+     * `ViewEncapsulation.Emulated`.
+     *
+     * If the policy is set to `ViewEncapsulation.Emulated` and the component has no `styles`
+     * or `styleUrls` specified, the policy is automatically switched to `ViewEncapsulation.None`.
      */
     encapsulation?: ViewEncapsulation;
     /**
-     * Overrides the default encapsulation start and end delimiters (respectively `{{` and `}}`)
+     * Overrides the default encapsulation start and end delimiters (`{{` and `}}`)
      */
     interpolation?: [string, string];
     /**
-     * Defines the components that should be compiled as well when
-     * this component is defined. For each components listed here,
-     * Angular will create a {@link ComponentFactory} and store it in the
+     * A set of components that should be compiled along with
+     * this component. For each component listed here,
+     * Angular creates a {@link ComponentFactory} and stores it in the
      * {@link ComponentFactoryResolver}.
      */
     entryComponents?: Array<Type<any> | any[]>;
     /**
-     * If {@link Component#preserveWhitespaces Component.preserveWhitespaces} is set to `false`
-     * potentially superfluous whitespace characters (ones matching the `\s` character class in
-     * JavaScript regular expressions) will be removed from a compiled template. This can greatly
-     * reduce AOT-generated code size as well as speed up view creation.
-     *
-     * Current implementation works according to the following rules:
-     * - all whitespaces at the beginning and the end of a template are removed (trimmed);
-     * - text nodes consisting of whitespaces only are removed (ex.:
-     *   `<button>Action 1</button>  <button>Action 2</button>` will be converted to
-     *   `<button>Action 1</button><button>Action 2</button>` (no whitespaces between buttons);
-     * - series of whitespaces in text nodes are replaced with one space (ex.:
-     *   `<span>\n some text\n</span>` will be converted to `<span> some text </span>`);
-     * - text nodes are left as-is inside HTML tags where whitespaces are significant (ex. `<pre>`,
-     *   `<textarea>`).
-     *
-     * Described transformations may (potentially) influence DOM nodes layout. However, the impact
-     * should so be minimal. That's why starting from Angular 6, the
-     * `preserveWhitespaces` option is `false` by default (whitespace removal).
-     * If you want to change the default setting for all components in your application you can use
-     * the `preserveWhitespaces` option of the AOT compiler.
-     *
-     * Even with the default behavior of whitespace removal, there are ways of preserving whitespaces
-     * in certain fragments of a template. You can either exclude entire DOM sub-tree by using the
-     * `ngPreserveWhitespaces` attribute, ex.:
-     *
-     * ```html
-     * <div ngPreserveWhitespaces>
-     *     whitespaces are preserved here
-     *     <span>    and here </span>
-     * </div>
-     * ```
-     *
-     * Alternatively you can force a space to be preserved in a text node by using the `&ngsp;`
-     * pseudo-entity. `&ngsp;` will be replaced with a space character by Angular's template
-     * compiler, ex.:
-     *
-     * ```html
-     * <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
-     * ```
-     *
-     * will be compiled to the equivalent of:
-     *
-     * ```html
-     * <a>Spaces</a> <a>between</a> <a>links.</a>
-     * ```
-     *
-     * Please note that sequences of `&ngsp;` are still collapsed to just one space character when
-     * the `preserveWhitespaces` option is set to `false`. Ex.:
-     *
-     * ```html
-     * <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
-     * ```
-     *
-     * would be equivalent to:
-     *
-     * ```html
-     * <a>before</a> <a>after</a>
-     * ```
-     *
-     * The `&ngsp;` pseudo-entity is useful for forcing presence of
-     * one space (a text node having `&ngsp;` pseudo-entities will never be removed), but it is not
-     * meant to mark sequences of whitespace characters. The previously described
-     * `ngPreserveWhitespaces` attribute is more useful for preserving sequences of whitespace
-     * characters.
+     * True to preserve or false to remove potentially superfluous whitespace characters
+     * from the compiled template. Whitespace characters are those matching the `\s`
+     * character class in JavaScript regular expressions. Default is false, unless
+     * overridden in compiler options.
      */
     preserveWhitespaces?: boolean;
 }
 /**
  * Component decorator and metadata.
  *
+ * @usageNotes
+ *
+ * ### Using animations
+ *
+ * The following snippet shows an animation trigger in a component's
+ * metadata. The trigger is attached to an element in the component's
+ * template, using "@_trigger_name_", and a state expression that is evaluated
+ * at run time to determine whether the animation should start.
+ *
+ * ```typescript
+ * @Component({
+ *   selector: 'animation-cmp',
+ *   templateUrl: 'animation-cmp.html',
+ *   animations: [
+ *     trigger('myTriggerName', [
+ *       state('on', style({ opacity: 1 }),
+ *       state('off', style({ opacity: 0 }),
+ *       transition('on => off', [
+ *         animate("1s")
+ *       ])
+ *     ])
+ *   ]
+ * })
+ * ```
+ *
+ * ```html
+ * <!-- animation-cmp.html -->
+ * <div @myTriggerName="expression">...</div>
+ * ```
+ *
+ * ### Preserving whitespace
+ *
+ * Removing whitespace can greatly reduce AOT-generated code size, and speed up view creation.
+ * As of Angular 6, default for `preserveWhitespaces` is false (whitespace is removed).
+ * To change the default setting for all components in your application, set
+ * the `preserveWhitespaces` option of the AOT compiler.
+ *
+ * Current implementation removes whitespace characters as follows:
+ * - Trims all whitespaces at the beginning and the end of a template.
+ * - Removes whitespace-only text nodes. For example,
+ * `<button>Action 1</button>  <button>Action 2</button>` becomes
+ * `<button>Action 1</button><button>Action 2</button>`.
+ * - Replaces a series of whitespace characters in text nodes with a single space.
+ * For example, `<span>\n some text\n</span>` becomes `<span> some text </span>`.
+ * - Does NOT alter text nodes inside HTML tags such as `<pre>` or `<textarea>`,
+ * where whitespace characters are significant.
+ *
+ * Note that these transformations can influence DOM nodes layout, although impact
+ * should be minimal.
+ *
+ * You can override the default behavior to preserve whitespace characters
+ * in certain fragments of a template. For example, you can exclude an entire
+ * DOM sub-tree by using the `ngPreserveWhitespaces` attribute:
+ *
+ * ```html
+ * <div ngPreserveWhitespaces>
+ *     whitespaces are preserved here
+ *     <span>    and here </span>
+ * </div>
+ * ```
+ *
+ * You can force a single space to be preserved in a text node by using `&ngsp;`,
+ * which is replaced with a space character by Angular's template
+ * compiler:
+ *
+ * ```html
+ * <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
+ * <!-->compiled to be equivalent to:</>
+ *  <a>Spaces</a> <a>between</a> <a>links.</a>
+ * ```
+ *
+ * Note that sequences of `&ngsp;` are still collapsed to just one space character when
+ * the `preserveWhitespaces` option is set to `false`.
+ *
+ * ```html
+ * <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
+ * <!-->compiled to be equivalent to:</>
+ *  <a>Spaces</a> <a>between</a> <a>links.</a>
+ * ```
+ *
+ * To preserve sequences of whitespace characters, use the
+ * `ngPreserveWhitespaces` attribute.
  *
  * @Annotation
  */
 export declare const Component: ComponentDecorator;
 /**
  * Type of the Pipe decorator / constructor function.
- *
- *
  */
 export interface PipeDecorator {
     /**
-     * Declare reusable pipe function.
-     *
-     * A "pure" pipe is only re-evaluated when either the input or any of the arguments change.
+     * Declares a reusable pipe function, and supplies configuration metadata.
      *
-     * When not specified, pipes default to being pure.
      */
     (obj: Pipe): TypeDecorator;
     /**
-     * See the {@link Pipe} decorator.
+     * See the `Pipe` decorator.
      */
     new (obj: Pipe): Pipe;
 }
 /**
  * Type of the Pipe metadata.
- *
- *
  */
 export interface Pipe {
     /**
-     * Name of the pipe.
+     * The pipe name to use in template bindings.
      *
-     * The pipe name is used in template bindings. For example if a pipe is named
-     * `myPipe` then it would be used in the template binding expression like
-     * so:  `{{ exp | myPipe }}`.
      */
     name: string;
     /**
-     * If Pipe is pure (its output depends only on its input.)
+     * When true, the pipe is pure, meaning that the
+     * `transform()` method is invoked only when its input arguments
+     * change. Pipes are pure by default.
      *
-     * Normally pipe's `transform` method is only invoked when the inputs to pipe`s
-     * `transform` method change. If the pipe has internal state (it's result are
-     * dependent on state other than its arguments) than set `pure` to `false` so
-     * that the pipe is invoked on each change-detection even if the arguments to the
-     * pipe do not change.
+     * If the pipe has internal state (that is, the result
+     * depends on state other than its arguments), set `pure` to false.
+     * In this case, the pipe is invoked on each change-detection cycle,
+     * even if the arguments have not changed.
      */
     pure?: boolean;
 }
 /**
- * Pipe decorator and metadata.
- *
- * Use the `@Pipe` annotation to declare that a given class is a pipe. A pipe
- * class must also implement {@link PipeTransform} interface.
- *
- * To use the pipe include a reference to the pipe class in
- * {@link NgModule#declarations}.
  *
  *
  * @Annotation
  */
 export declare const Pipe: PipeDecorator;
 /**
- * Type of the Input decorator / constructor function.
- *
  *
  */
 export interface InputDecorator {
     /**
-     * Declares a data-bound input property.
+     * Decorator that marks a class as pipe and supplies configuration metadata.
      *
-     * Angular automatically updates data-bound properties during change detection.
+     * A pipe class must implement the `PipeTransform` interface.
+     * For example, if the name is "myPipe", use a template binding expression
+     * such as the following:
      *
-     * `Input` takes an optional parameter that specifies the name
-     * used when instantiating a component in the template. When not provided,
-     * the name of the decorated property is used.
+     * ```
+     * {{ exp | myPipe }}
+     * ```
      *
-     * ### Example
+     * The result of the expression is passed to the pipe's `transform()` method.
      *
-     * The following example creates a component with two input properties.
+     * A pipe must belong to an NgModule in order for it to be available
+     * to a template. To make it a member of an NgModule,
+     * list it in the `declarations` field of the `@NgModule` metadata.
+     *
+     */
+    (bindingPropertyName?: string): any;
+    new (bindingPropertyName?: string): any;
+}
+/**
+ * Type of metadata for an `Input` property.
+ *
+ *
+ */
+export interface Input {
+    /**
+     * Decorator that marks a class field as an input property and supplies configuration metadata.
+     * Declares a data-bound input property, which Angular automatically updates
+     * during change detection.
+     *
+     * @usageNotes
+     *
+     * You can supply an optional name to use in templates when the
+     * component is instantiated, that maps to the
+     * name of the bound property. By default, the original
+     * name of the bound property is used for input binding.
+     *
+     * The following example creates a component with two input properties,
+     * one of which is given a special binding name.
      *
      * ```typescript
      * @Component({
      *   selector: 'bank-account',
      *   template: `
      *     Bank Name: {{bankName}}
-     *     Account Id: {{id}}
+    *      Account Id: {{id}}
      *   `
      * })
      * class BankAccount {
+     *   // This property is bound using its original name.
      *   @Input() bankName: string;
+     *   // this property value is bound to a different property name
+     *   // when this component is instantiated in a template.
      *   @Input('account-id') id: string;
      *
-     *   // this property is not bound, and won't be automatically updated by Angular
+     *   // this property is not bound, and is not automatically updated by Angular
      *   normalizedBankName: string;
      * }
      *
@@ -830,118 +841,66 @@ export interface InputDecorator {
      *
      * class App {}
      * ```
-     *
-     */
-    (bindingPropertyName?: string): any;
-    new (bindingPropertyName?: string): any;
-}
-/**
- * Type of the Input metadata.
- *
- *
- */
-export interface Input {
-    /**
-     * Name used when instantiating a component in the template.
      */
     bindingPropertyName?: string;
 }
 /**
- * Input decorator and metadata.
- *
  *
  * @Annotation
  */
 export declare const Input: InputDecorator;
 /**
  * Type of the Output decorator / constructor function.
- *
- *
  */
 export interface OutputDecorator {
     /**
-     * Declares an event-bound output property.
-     *
-     * When an output property emits an event, an event handler attached to that event
-     * the template is invoked.
-     *
-     * `Output` takes an optional parameter that specifies the name
-     * used when instantiating a component in the template. When not provided,
-     * the name of the decorated property is used.
-     *
-     * ### Example
-     *
-     * ```typescript
-     * @Directive({
-     *   selector: 'interval-dir',
-     * })
-     * class IntervalDir {
-     *   @Output() everySecond = new EventEmitter();
-     *   @Output('everyFiveSeconds') five5Secs = new EventEmitter();
-     *
-     *   constructor() {
-     *     setInterval(() => this.everySecond.emit("event"), 1000);
-     *     setInterval(() => this.five5Secs.emit("event"), 5000);
-     *   }
-     * }
-     *
-     * @Component({
-     *   selector: 'app',
-     *   template: `
-     *     <interval-dir (everySecond)="everySecond()" (everyFiveSeconds)="everyFiveSeconds()">
-     *     </interval-dir>
-     *   `
-     * })
-     * class App {
-     *   everySecond() { console.log('second'); }
-     *   everyFiveSeconds() { console.log('five seconds'); }
-     * }
-     * ```
-     *
-     */
+    * Decorator that marks a class field as an output property and supplies configuration metadata.
+    * Declares a data-bound output property, which Angular automatically updates
+    * during change detection.
+    *
+    * @usageNotes
+    *
+    * You can supply an optional name to use in templates when the
+    * component is instantiated, that maps to the
+    * name of the bound property. By default, the original
+    * name of the bound property is used for output binding.
+    *
+    * See `@Input` decorator for an example of providing a binding name.
+    *
+    */
     (bindingPropertyName?: string): any;
     new (bindingPropertyName?: string): any;
 }
 /**
  * Type of the Output metadata.
- *
- *
  */
 export interface Output {
     bindingPropertyName?: string;
 }
 /**
- * Output decorator and metadata.
- *
  *
  * @Annotation
  */
 export declare const Output: OutputDecorator;
 /**
  * Type of the HostBinding decorator / constructor function.
- *
- *
  */
 export interface HostBindingDecorator {
     /**
-     * Declares a host property binding.
-     *
-     * Angular automatically checks host property bindings during change detection.
-     * If a binding changes, it will update the host element of the directive.
-     *
-     * `HostBinding` takes an optional parameter that specifies the property
-     * name of the host element that will be updated. When not provided,
-     * the class property name is used.
+     * Decorator that marks a DOM property as a host-binding property and supplies configuration
+     * metadata.
+     * Angular automatically checks host property bindings during change detection, and
+     * if a binding changes it updates the host element of the directive.
      *
-     * ### Example
+     * @usageNotes
      *
-     * The following example creates a directive that sets the `valid` and `invalid` classes
-     * on the DOM element that has ngModel directive on it.
+     * The following example creates a directive that sets the `valid` and `invalid`
+     * properties on the DOM element that has an `ngModel` directive on it.
      *
      * ```typescript
      * @Directive({selector: '[ngModel]'})
      * class NgModelStatus {
-     *   constructor(public control:NgModel) {}
+     *   constructor(public control: NgModel) {}
      *   @HostBinding('class.valid') get valid() { return this.control.valid; }
      *   @HostBinding('class.invalid') get invalid() { return this.control.invalid; }
      * }
@@ -954,7 +913,6 @@ export interface HostBindingDecorator {
      *   prop;
      * }
      * ```
-     *
      */
     (hostPropertyName?: string): any;
     new (hostPropertyName?: string): any;
@@ -962,71 +920,63 @@ export interface HostBindingDecorator {
 /**
  * Type of the HostBinding metadata.
  *
- *
  */
 export interface HostBinding {
     hostPropertyName?: string;
 }
 /**
- * HostBinding decorator and metadata.
- *
  *
  * @Annotation
  */
 export declare const HostBinding: HostBindingDecorator;
 /**
  * Type of the HostListener decorator / constructor function.
- *
- *
  */
 export interface HostListenerDecorator {
-    /**
-     * Declares a host listener.
-     *
-     * Angular will invoke the decorated method when the host element emits the specified event.
-     *
-     * If the decorated method returns `false`, then `preventDefault` is applied on the DOM event.
-     *
-     * ### Example
-     *
-     * The following example declares a directive that attaches a click listener to the button and
-     * counts clicks.
-     *
-     * ```typescript
-     * @Directive({selector: 'button[counting]'})
-     * class CountClicks {
-     *   numberOfClicks = 0;
-     *
-     *   @HostListener('click', ['$event.target'])
-     *   onClick(btn) {
-     *     console.log('button', btn, 'number of clicks:', this.numberOfClicks++);
-     *   }
-     * }
-     *
-     * @Component({
-     *   selector: 'app',
-     *   template: '<button counting>Increment</button>',
-     * })
-     * class App {}
-     * ```
-     *
-     * @Annotation
-     */
     (eventName: string, args?: string[]): any;
     new (eventName: string, args?: string[]): any;
 }
 /**
  * Type of the HostListener metadata.
- *
- *
  */
 export interface HostListener {
+    /**
+     * The CSS event to listen for.
+     */
     eventName?: string;
+    /**
+     * A set of arguments to pass to the handler method when the event occurs.
+     */
     args?: string[];
 }
 /**
- * HostListener decorator and metadata.
- *
+ * Binds a CSS event to a host listener and supplies configuration metadata.
+ * Angular invokes the supplied handler method when the host element emits the specified event,
+ * and updates the bound element with the result.
+ * If the handler method returns false, applies `preventDefault` on the bound element.
+ *
+ * @usageNotes
+ *
+ * The following example declares a directive
+ * that attaches a click listener to a button and counts clicks.
+ *
+ * ```
+ * @Directive({selector: 'button[counting]'})
+ * class CountClicks {
+ *   numberOfClicks = 0;
+ *
+ *   @HostListener('click', ['$event.target'])
+ *   onClick(btn) {
+ *     console.log('button', btn, 'number of clicks:', this.numberOfClicks++);
+ *  }
+ * }
+ *
+ * @Component({
+ *   selector: 'app',
+ *   template: '<button counting>Increment</button>',
+ * })
+ * class App {}
+ * ```
  *
  * @Annotation
  */