diff --git a/angular-odata-resources/angular-odata-resources-tests.ts b/angular-odata-resources/angular-odata-resources-tests.ts index 5b8dbcc52..23286adc0 100644 --- a/angular-odata-resources/angular-odata-resources-tests.ts +++ b/angular-odata-resources/angular-odata-resources-tests.ts @@ -197,3 +197,12 @@ users = odataResourceClass.odata() var countResult = odataResourceClass.odata().count(); var total = countResult.result; + + + +var usersSelect1 = odataResourceClass.odata() + .select('name', 'user'); + + +var usersSelect2 = odataResourceClass.odata() + .select(['name', 'user']); \ No newline at end of file diff --git a/angular-odata-resources/angular-odata-resources.d.ts b/angular-odata-resources/angular-odata-resources.d.ts index 0a83df2c3..7c625d40c 100644 --- a/angular-odata-resources/angular-odata-resources.d.ts +++ b/angular-odata-resources/angular-odata-resources.d.ts @@ -267,6 +267,7 @@ declare module OData { interface ICountResult{ result: number; + $promise: angular.IPromise; } class Provider { @@ -278,14 +279,17 @@ declare module OData { private expandables; constructor(callback: ProviderCallback); filter(operand1: any, operand2?: any, operand3?: any): Provider; - orderBy(arg1: any, arg2?: any): Provider; + orderBy(arg1: string, arg2?: string): Provider; take(amount: number): Provider; skip(amount: number): Provider; private execute(); - query(success?: any, error?: any): T[]; - single(success?: any, error?: any): T; - get(data: any, success?: any, error?: any): T; - expand(params: any, otherParam1?: any, otherParam2?: any, otherParam3?: any, otherParam4?: any, otherParam5?: any, otherParam6?: any, otherParam7?: any): Provider; + query(success?: ((p:T[])=>void), error?: (()=>void)): T[]; + single(success?: ((p:T)=>void), error?: (()=>void)): T; + get(key: any, success?: ((p:T)=>void), error?: (()=>void)): T; + expand(...params: string[]): Provider; + expand(params: string[]): Provider; + select(...params: string[]): Provider; + select(params: string[]): Provider; count(success?: (result: ICountResult) => any, error?: () => any):ICountResult; withInlineCount(): Provider; } diff --git a/angular-protractor/angular-protractor.d.ts b/angular-protractor/angular-protractor.d.ts index 2b86864cd..ff8324238 100644 --- a/angular-protractor/angular-protractor.d.ts +++ b/angular-protractor/angular-protractor.d.ts @@ -1228,7 +1228,21 @@ declare module protractor { row(index: number): LocatorWithColumn; } - interface IProtractorLocatorStrategy extends webdriver.ILocatorStrategy { + interface IProtractorLocatorStrategy { + /** + * webdriver's By is an enum of locator functions, so we must set it to + * a prototype before inheriting from it. + */ + className: typeof webdriver.By.className; + css: typeof webdriver.By.css; + id: typeof webdriver.By.id; + linkText: typeof webdriver.By.linkText; + js: typeof webdriver.By.js; + name: typeof webdriver.By.name; + partialLinkText: typeof webdriver.By.partialLinkText; + tagName: typeof webdriver.By.tagName; + xpath: typeof webdriver.By.xpath; + /** * Add a locator to this instance of ProtractorBy. This locator can then be * used with element(by.locatorName(args)). diff --git a/angular-ui-router/angular-ui-router-tests.ts b/angular-ui-router/angular-ui-router-tests.ts index a05f13dd8..dccd8f7b1 100644 --- a/angular-ui-router/angular-ui-router-tests.ts +++ b/angular-ui-router/angular-ui-router-tests.ts @@ -14,12 +14,28 @@ myApp.config(( var matcher: ng.ui.IUrlMatcher = $urlMatcherFactory.compile("/foo/:bar?param1"); + $urlMatcherFactory.caseInsensitive(false); + var isCaseInsensitive = $urlMatcherFactory.caseInsensitive(); + + $urlMatcherFactory.defaultSquashPolicy("nosquash"); + + $urlMatcherFactory.strictMode(true); + var isStrictMode = $urlMatcherFactory.strictMode(); + $urlMatcherFactory.type("myType2", { encode: function (item: any) { return item; }, decode: function (item: any) { return item; }, is: function (item: any) { return true; } }); + $urlMatcherFactory.type("fullType", { + decode: (val) => parseInt(val, 10), + encode: (val) => val && val.toString(), + equals: (a, b) => this.is(a) && a === b, + is: (val) => angular.isNumber(val) && isFinite(val) && val % 1 === 0, + pattern: /\d+/ + }); + var obj: Object = matcher.exec('/user/bob', { x:'1', q:'hello' }); var concat: ng.ui.IUrlMatcher = matcher.concat('/test'); var str: string = matcher.format({ id:'bob', q:'yes' }); @@ -177,3 +193,35 @@ module UiViewScrollProviderTests { $uiViewScrollProvider.useAnchorScroll(); }]); } + +interface ITestUserService { + isLoggedIn: () => boolean; + handleLogin: () => ng.IPromise<{}>; +} + +module UrlRouterProviderTests { + var app = angular.module("urlRouterProviderTests", ["ui.router"]); + + app.config(($urlRouterProvider: ng.ui.IUrlRouterProvider) => { + // Prevent $urlRouter from automatically intercepting URL changes; + // this allows you to configure custom behavior in between + // location changes and route synchronization: + $urlRouterProvider.deferIntercept(); + }).run(($rootScope: ng.IRootScopeService, $urlRouter: ng.ui.IUrlRouterService, UserService: ITestUserService) => { + $rootScope.$on('$locationChangeSuccess', e => { + // UserService is an example service for managing user state + if (UserService.isLoggedIn()) return; + + // Prevent $urlRouter's default handler from firing + e.preventDefault(); + + UserService.handleLogin().then(() => { + // Once the user has logged in, sync the current URL to the router: + $urlRouter.sync(); + }); + }); + + // Configures $urlRouter's listener *after* your custom listener + $urlRouter.listen(); + }); +} diff --git a/angular-ui-router/angular-ui-router.d.ts b/angular-ui-router/angular-ui-router.d.ts index 10b92db7d..febe1c090 100644 --- a/angular-ui-router/angular-ui-router.d.ts +++ b/angular-ui-router/angular-ui-router.d.ts @@ -91,12 +91,70 @@ declare module angular.ui { } interface IUrlMatcherFactory { + /** + * Creates a UrlMatcher for the specified pattern. + * + * @param pattern {string} The URL pattern. + * + * @returns {IUrlMatcher} The UrlMatcher. + */ compile(pattern: string): IUrlMatcher; + /** + * Returns true if the specified object is a UrlMatcher, or false otherwise. + * + * @param o {any} The object to perform the type check against. + * + * @returns {boolean} Returns true if the object matches the IUrlMatcher interface, by implementing all the same methods. + */ isMatcher(o: any): boolean; - type(name: string, definition: any, definitionFn?: any): any; - caseInsensitive(value: boolean): void; + /** + * Returns a type definition for the specified name + * + * @param name {string} The type definition name + * + * @returns {IType} The type definition + */ + type(name: string): IType; + /** + * Registers a custom Type object that can be used to generate URLs with typed parameters. + * + * @param {IType} definition The type definition. + * @param {any[]} inlineAnnotedDefinitionFn A function that is injected before the app runtime starts. The result of this function is merged into the existing definition. + * + * @returns {IUrlMatcherFactory} Returns $urlMatcherFactoryProvider. + */ + type(name: string, definition: IType, inlineAnnotedDefinitionFn?: any[]): IUrlMatcherFactory; + /** + * Registers a custom Type object that can be used to generate URLs with typed parameters. + * + * @param {IType} definition The type definition. + * @param {any[]} inlineAnnotedDefinitionFn A function that is injected before the app runtime starts. The result of this function is merged into the existing definition. + * + * @returns {IUrlMatcherFactory} Returns $urlMatcherFactoryProvider. + */ + type(name: string, definition: IType, definitionFn?: (...args:any[]) => IType): IUrlMatcherFactory; + /** + * Defines whether URL matching should be case sensitive (the default behavior), or not. + * + * @param value {boolean} false to match URL in a case sensitive manner; otherwise true; + * + * @returns {boolean} the current value of caseInsensitive + */ + caseInsensitive(value?: boolean): boolean; + /** + * Sets the default behavior when generating or matching URLs with default parameter values + * + * @param value {string} A string that defines the default parameter URL squashing behavior. nosquash: When generating an href with a default parameter value, do not squash the parameter value from the URL slash: When generating an href with a default parameter value, squash (remove) the parameter value, and, if the parameter is surrounded by slashes, squash (remove) one slash from the URL any other string, e.g. "~": When generating an href with a default parameter value, squash (remove) the parameter value from the URL and replace it with this string. + */ defaultSquashPolicy(value: string): void; - strictMode(value: boolean): void; + /** + * Defines whether URLs should match trailing slashes, or not (the default behavior). + * + * @param value {boolean} false to match trailing slashes in URLs, otherwise true. + * + * @returns {boolean} the current value of strictMode + */ + strictMode(value?: boolean): boolean; } interface IUrlRouterProvider extends angular.IServiceProvider { @@ -114,6 +172,14 @@ declare module angular.ui { otherwise(path: string): IUrlRouterProvider; rule(handler: Function): IUrlRouterProvider; rule(handler: any[]): IUrlRouterProvider; + /** + * Disables (or enables) deferring location change interception. + * + * If you wish to customize the behavior of syncing the URL (for example, if you wish to defer a transition but maintain the current URL), call this method at configuration time. Then, at run time, call $urlRouter.listen() after you have configured your own $locationChangeSuccess event handler. + * + * @param {boolean} defer Indicates whether to defer location change interception. Passing no parameter is equivalent to true. + */ + deferIntercept(defer?: boolean): void; } interface IStateOptions { @@ -203,6 +269,7 @@ declare module angular.ui { * */ sync(): void; + listen(): void; } interface IUiViewScrollProvider { @@ -212,4 +279,47 @@ declare module angular.ui { */ useAnchorScroll(): void; } + + interface IType { + /** + * Converts a parameter value (from URL string or transition param) to a custom/native value. + * + * @param val {string} The URL parameter value to decode. + * @param key {string} The name of the parameter in which val is stored. Can be used for meta-programming of Type objects. + * + * @returns {any} Returns a custom representation of the URL parameter value. + */ + decode(val: string, key: string): any; + /** + * Encodes a custom/native type value to a string that can be embedded in a URL. Note that the return value does not need to be URL-safe (i.e. passed through encodeURIComponent()), it only needs to be a representation of val that has been coerced to a string. + * + * @param val {any} The value to encode. + * @param key {string} The name of the parameter in which val is stored. Can be used for meta-programming of Type objects. + * + * @returns {string} Returns a string representation of val that can be encoded in a URL. + */ + encode(val: any, key: string): string; + /** + * Determines whether two decoded values are equivalent. + * + * @param a {any} A value to compare against. + * @param b {any} A value to compare against. + * + * @returns {boolean} Returns true if the values are equivalent/equal, otherwise false. + */ + equals? (a: any, b: any): boolean; + /** + * Detects whether a value is of a particular type. Accepts a native (decoded) value and determines whether it matches the current Type object. + * + * @param val {any} The value to check. + * @param key {any} Optional. If the type check is happening in the context of a specific UrlMatcher object, this is the name of the parameter in which val is stored. Can be used for meta-programming of Type objects. + * + * @returns {boolean} Returns true if the value matches the type, otherwise false. + */ + is(val: any, key: string): boolean; + /** + * The regular expression pattern used to match values of this type when coming from a substring of a URL. + */ + pattern?: RegExp; + } } diff --git a/angular-ui-scroll/angular-ui-scroll-tests.ts b/angular-ui-scroll/angular-ui-scroll-tests.ts new file mode 100644 index 000000000..1a85dd6b5 --- /dev/null +++ b/angular-ui-scroll/angular-ui-scroll-tests.ts @@ -0,0 +1,93 @@ +/// +var myApp = angular.module('application', ['ui.scroll', 'ui.scroll.jqlite']); + +module application { + interface IItem { + id: number; + content: string; + } + + class DatasourceTest implements ng.ui.IScrollDatasource { + get(index: number, count: number, success: (results: IItem[]) => void): void { + var ret = new Array(); + for (var i=0; i < count; i++) { + ret.push({id: i, content: 'item ' + i.toString()}); + } + success(ret); + } + } + + function factory(): any { + return DatasourceTest; + } + + myApp.factory('DatasourceTest', factory); + + // demo/examples/adapter + myApp.controller('mainController', ['$scope', 'DatasourceTest', function($scope: ng.IScope, datasource: DatasourceTest) { + var firstListAdapter: ng.ui.IScrollAdapter, secondListAdapter: ng.ui.IScrollAdapter; + $scope['datasource'] = datasource; + + $scope['updateList1'] = (): void => { + firstListAdapter.applyUpdates( (item: IItem, scope: ng.IRepeatScope) => { + return item.content += ' *'; + }) + }; + + $scope['removeFromList1'] = (): void => { + firstListAdapter.applyUpdates( (item: IItem, scope: ng.IRepeatScope) => { + if (scope.$index % 2 === 0) { + return [] + } + }) + }; + + var idList1: number = 1000; + $scope['addToList1'] = (): void => { + firstListAdapter.applyUpdates((item: IItem, scope: ng.IRepeatScope) => { + var newItem: IItem; + newItem = void 0; + if (scope.$index === 2) { + newItem = { + id: idList1, + content: 'a new one #' + idList1 + }; + idList1++; + return [item, newItem]; + } + }); + }; + + $scope['updateList2'] = (): void => { + secondListAdapter.applyUpdates((item: IItem, scope: ng.IRepeatScope) => { + return item.content += ' *'; + }); + }; + + $scope['removeFromList2'] = (): void => { + secondListAdapter.applyUpdates((item: IItem, scope: ng.IRepeatScope) => { + if (scope.$index % 2 !== 0) { + return []; + } + }); + }; + + var idList2: number = 2000; + $scope['addToList2'] = (): void => { + secondListAdapter.applyUpdates((item: IItem, scope: ng.IRepeatScope) => { + var newItem: IItem; + newItem = void 0; + if (scope.$index === 4) { + newItem = { + id: idList2, + content: 'a new one #' + idList1 + }; + idList2++; + return [item, newItem]; + } + }); + }; + + }]); +} + diff --git a/angular-ui-scroll/angular-ui-scroll.d.ts b/angular-ui-scroll/angular-ui-scroll.d.ts new file mode 100644 index 000000000..08ed233c0 --- /dev/null +++ b/angular-ui-scroll/angular-ui-scroll.d.ts @@ -0,0 +1,85 @@ +// Type definitions for Angular JS 1.3.1+ (ui.scroll module) +// Project: https://github.com/angular-ui/ui-scroll +// Definitions by: Mark Nadig +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/// + +declare module angular.ui { + interface IScrollDatasource { + /** + * The datasource object implements methods and properties to be used by the directive to access the data + * + * @param index indicates the first data row requested + * + * @param count indicates number of data rows requested + * + * @param success function to call when the data are retrieved. The implementation of the service has to call + * this function when the data are retrieved and pass it an array of the items retrieved. If no items are + * retrieved, an empty array has to be passed. + * + * Important: Make sure to respect the index and count parameters of the request. The array passed to the + * success method should have exactly count elements unless it hit eof/bof + */ + get(index: number, count: number, success: (results: Array) => any): void; + } + + interface IScrollAdapter { + /** + * a boolean value indicating whether there are any pending load requests. + */ + isLoading: boolean; + /** + * a reference to the item currently in the topmost visible position. + */ + topVisible: any; + /** + * a reference to the DOM element currently in the topmost visible position. + */ + topVisibleElement: ng.IAugmentedJQueryStatic; + /** + * a reference to the scope created for the item currently in the topmost visible position. + */ + topVisibleScope: ng.IRepeatScope; + /** + * calling this method reinitializes and reloads the scroller content. + */ + reload(): void; + /** + * Replaces the item in the buffer at the given index with the new items. + * + * @param index provides position of the item to be affected in the dataset (not in the buffer). If the item with + * the given index currently is not in the buffer no updates will be applied. $index property of the item $scope + * can be used to access the index value for a given item + * + * @param newItems is an array of items to replace the affected item. If the array is empty ([]) the item will + * be deleted, otherwise the items in the array replace the item. If the newItem array contains the old item, + * the old item stays in place. + */ + applyUpdates(index: number, newItems: any[]): void; + /** + * Replaces the item in the buffer at the given index with the new items. + * + * @param updater is a function to be applied to every item currently in the buffer. The function will receive + * 3 parameters: item, scope, and element. Here item is the item to be affected, scope is the item $scope, and + * element is the html element for the item. The return value of the function should be an array of items. + * Similarly to the newItem parameter (see above), if the array is empty([]), the item is deleted, otherwise + * the item is replaced by the items in the array. If the return value is not an array, the item remains + * unaffected, unless some updates were made to the item in the updater function. This can be thought of as + * in place update. + */ + applyUpdates(updater: (item: any, scope: ng.IRepeatScope) => any): void; + /** + * Adds new items after the last item in the buffer + * + * @param newItems provides an array of items to be appended. + */ + append(newItems: any[]): void; + /** + * Adds new items before the first item in the buffer + * + * @param newItems provides an array of items to be prepended. + */ + prepend(newItems: any[]): void; + } +} diff --git a/angular2/angular2-2.0.0-alpha.35.d.ts b/angular2/angular2-2.0.0-alpha.35.d.ts new file mode 100644 index 000000000..4c9c2aea2 --- /dev/null +++ b/angular2/angular2-2.0.0-alpha.35.d.ts @@ -0,0 +1,5775 @@ +// Type definitions for Angular v2.0.0-alpha.35 +// Project: http://angular.io/ +// Definitions by: angular team +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +// *********************************************************** +// This file is generated by the Angular build process. +// Please do not create manual edits or send pull requests +// modifying this file. +// *********************************************************** + +// angular2/angular2 depends transitively on these libraries. +// If you don't have them installed you can install them using TSD +// https://github.com/DefinitelyTyped/tsd + +/// +/// + + +interface List extends Array {} +interface Map {} +interface StringMap extends Map {} + +declare module ng { + // See https://github.com/Microsoft/TypeScript/issues/1168 + class BaseException /* extends Error */ { + message: string; + stack: string; + toString(): string; + } + interface InjectableReference {} +} + + + + +/** + * The `angular2` is the single place to import all of the individual types. + */ +declare module ng { + + /** + * Declare reusable UI building blocks for an application. + * + * Each Angular component requires a single `@Component` and at least one `@View` annotation. The + * `@Component` + * annotation specifies when a component is instantiated, and which properties and hostListeners it + * binds to. + * + * When a component is instantiated, Angular + * - creates a shadow DOM for the component. + * - loads the selected template into the shadow DOM. + * - creates all the injectable objects configured with `bindings` and `viewBindings`. + * + * All template expressions and statements are then evaluated against the component instance. + * + * For details on the `@View` annotation, see {@link ViewMetadata}. + * + * ## Example + * + * ``` + * @Component({ + * selector: 'greet' + * }) + * @View({ + * template: 'Hello {{name}}!' + * }) + * class Greet { + * name: string; + * + * constructor() { + * this.name = 'World'; + * } + * } + * ``` + */ + class ComponentMetadata extends DirectiveMetadata { + + + /** + * Defines the used change detection strategy. + * + * When a component is instantiated, Angular creates a change detector, which is responsible for + * propagating + * the component's bindings. + * + * The `changeDetection` property defines, whether the change detection will be checked every time + * or only when the component + * tells it to do so. + */ + changeDetection: string; + + + /** + * Defines the set of injectable objects that are visible to its view dom children. + * + * ## Simple Example + * + * Here is an example of a class that can be injected: + * + * ``` + * class Greeter { + * greet(name:string) { + * return 'Hello ' + name + '!'; + * } + * } + * + * @Directive({ + * selector: 'needs-greeter' + * }) + * class NeedsGreeter { + * greeter:Greeter; + * + * constructor(greeter:Greeter) { + * this.greeter = greeter; + * } + * } + * + * @Component({ + * selector: 'greet', + * viewBindings: [ + * Greeter + * ] + * }) + * @View({ + * template: ``, + * directives: [NeedsGreeter] + * }) + * class HelloWorld { + * } + * + * ``` + */ + viewBindings: List; + } + + + /** + * Directives allow you to attach behavior to elements in the DOM. + * + * {@link DirectiveMetadata}s with an embedded view are called {@link ComponentMetadata}s. + * + * A directive consists of a single directive annotation and a controller class. When the + * directive's `selector` matches + * elements in the DOM, the following steps occur: + * + * 1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor + * arguments. + * 2. Angular instantiates directives for each matched element using `ElementInjector` in a + * depth-first order, + * as declared in the HTML. + * + * ## Understanding How Injection Works + * + * There are three stages of injection resolution. + * - *Pre-existing Injectors*: + * - The terminal {@link Injector} cannot resolve dependencies. It either throws an error or, if + * the dependency was + * specified as `@Optional`, returns `null`. + * - The platform injector resolves browser singleton resources, such as: cookies, title, + * location, and others. + * - *Component Injectors*: Each component instance has its own {@link Injector}, and they follow + * the same parent-child hierarchy + * as the component instances in the DOM. + * - *Element Injectors*: Each component instance has a Shadow DOM. Within the Shadow DOM each + * element has an `ElementInjector` + * which follow the same parent-child hierarchy as the DOM elements themselves. + * + * When a template is instantiated, it also must instantiate the corresponding directives in a + * depth-first order. The + * current `ElementInjector` resolves the constructor dependencies for each directive. + * + * Angular then resolves dependencies as follows, according to the order in which they appear in the + * {@link ViewMetadata}: + * + * 1. Dependencies on the current element + * 2. Dependencies on element injectors and their parents until it encounters a Shadow DOM boundary + * 3. Dependencies on component injectors and their parents until it encounters the root component + * 4. Dependencies on pre-existing injectors + * + * + * The `ElementInjector` can inject other directives, element-specific special objects, or it can + * delegate to the parent + * injector. + * + * To inject other directives, declare the constructor parameter as: + * - `directive:DirectiveType`: a directive on the current element only + * - `@Host() directive:DirectiveType`: any directive that matches the type between the current + * element and the + * Shadow DOM root. + * - `@Query(DirectiveType) query:QueryList`: A live collection of direct child + * directives. + * - `@QueryDescendants(DirectiveType) query:QueryList`: A live collection of any + * child directives. + * + * To inject element-specific special objects, declare the constructor parameter as: + * - `element: ElementRef` to obtain a reference to logical element in the view. + * - `viewContainer: ViewContainerRef` to control child template instantiation, for + * {@link DirectiveMetadata} directives only + * - `bindingPropagation: BindingPropagation` to control change detection in a more granular way. + * + * ## Example + * + * The following example demonstrates how dependency injection resolves constructor arguments in + * practice. + * + * + * Assume this HTML template: + * + * ``` + *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ``` + * + * With the following `dependency` decorator and `SomeService` injectable class. + * + * ``` + * @Injectable() + * class SomeService { + * } + * + * @Directive({ + * selector: '[dependency]', + * properties: [ + * 'id: dependency' + * ] + * }) + * class Dependency { + * id:string; + * } + * ``` + * + * Let's step through the different ways in which `MyDirective` could be declared... + * + * + * ### No injection + * + * Here the constructor is declared with no arguments, therefore nothing is injected into + * `MyDirective`. + * + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor() { + * } + * } + * ``` + * + * This directive would be instantiated with no dependencies. + * + * + * ### Component-level injection + * + * Directives can inject any injectable instance from the closest component injector or any of its + * parents. + * + * Here, the constructor declares a parameter, `someService`, and injects the `SomeService` type + * from the parent + * component's injector. + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(someService: SomeService) { + * } + * } + * ``` + * + * This directive would be instantiated with a dependency on `SomeService`. + * + * + * ### Injecting a directive from the current element + * + * Directives can inject other directives declared on the current element. + * + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(dependency: Dependency) { + * expect(dependency.id).toEqual(3); + * } + * } + * ``` + * This directive would be instantiated with `Dependency` declared at the same element, in this case + * `dependency="3"`. + * + * ### Injecting a directive from any ancestor elements + * + * Directives can inject other directives declared on any ancestor element (in the current Shadow + * DOM), i.e. on the current element, the + * parent element, or its parents. + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(@Host() dependency: Dependency) { + * expect(dependency.id).toEqual(2); + * } + * } + * ``` + * + * `@Host` checks the current element, the parent, as well as its parents recursively. If + * `dependency="2"` didn't + * exist on the direct parent, this injection would + * have returned + * `dependency="1"`. + * + * + * ### Injecting a live collection of direct child directives + * + * + * A directive can also query for other child directives. Since parent directives are instantiated + * before child directives, a directive can't simply inject the list of child directives. Instead, + * the directive injects a {@link QueryList}, which updates its contents as children are added, + * removed, or moved by a directive that uses a {@link ViewContainerRef} such as a `ng-for`, an + * `ng-if`, or an `ng-switch`. + * + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(@Query(Dependency) dependencies:QueryList) { + * } + * } + * ``` + * + * This directive would be instantiated with a {@link QueryList} which contains `Dependency` 4 and + * 6. Here, `Dependency` 5 would not be included, because it is not a direct child. + * + * ### Injecting a live collection of descendant directives + * + * By passing the descendant flag to `@Query` above, we can include the children of the child + * elements. + * + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(@Query(Dependency, {descendants: true}) dependencies:QueryList) { + * } + * } + * ``` + * + * This directive would be instantiated with a Query which would contain `Dependency` 4, 5 and 6. + * + * ### Optional injection + * + * The normal behavior of directives is to return an error when a specified dependency cannot be + * resolved. If you + * would like to inject `null` on unresolved dependency instead, you can annotate that dependency + * with `@Optional()`. + * This explicitly permits the author of a template to treat some of the surrounding directives as + * optional. + * + * ``` + * @Directive({ selector: '[my-directive]' }) + * class MyDirective { + * constructor(@Optional() dependency:Dependency) { + * } + * } + * ``` + * + * This directive would be instantiated with a `Dependency` directive found on the current element. + * If none can be + * found, the injector supplies `null` instead of throwing an error. + * + * ## Example + * + * Here we use a decorator directive to simply define basic tool-tip behavior. + * + * ``` + * @Directive({ + * selector: '[tooltip]', + * properties: [ + * 'text: tooltip' + * ], + * host: { + * '(mouseenter)': 'onMouseEnter()', + * '(mouseleave)': 'onMouseLeave()' + * } + * }) + * class Tooltip{ + * text:string; + * overlay:Overlay; // NOT YET IMPLEMENTED + * overlayManager:OverlayManager; // NOT YET IMPLEMENTED + * + * constructor(overlayManager:OverlayManager) { + * this.overlay = overlay; + * } + * + * onMouseEnter() { + * // exact signature to be determined + * this.overlay = this.overlayManager.open(text, ...); + * } + * + * onMouseLeave() { + * this.overlay.close(); + * this.overlay = null; + * } + * } + * ``` + * In our HTML template, we can then add this behavior to a `
` or any other element with the + * `tooltip` selector, + * like so: + * + * ``` + *
+ * ``` + * + * Directives can also control the instantiation, destruction, and positioning of inline template + * elements: + * + * A directive uses a {@link ViewContainerRef} to instantiate, insert, move, and destroy views at + * runtime. + * The {@link ViewContainerRef} is created as a result of `