UNPKG

17 kBTypeScriptView Raw
1/**
2 * @license Angular v12.2.8
3 * (c) 2010-2021 Google LLC. https://angular.io/
4 * License: MIT
5 */
6
7import { CompilerOptions } from '@angular/core';
8import { Injector } from '@angular/core';
9import { NgModuleRef } from '@angular/core';
10import { Type } from '@angular/core';
11import { Version } from '@angular/core';
12
13declare interface IAngularBootstrapConfig {
14 strictDi?: boolean;
15}
16
17declare interface IInjectorService {
18 get(key: string): any;
19 has(key: string): boolean;
20}
21
22declare interface IRootScopeService {
23 $new(isolate?: boolean): IScope;
24 $id: string;
25 $parent: IScope;
26 $root: IScope;
27 $watch(exp: Ng1Expression, fn?: (a1?: any, a2?: any) => void): Function;
28 $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function;
29 $destroy(): any;
30 $apply(exp?: Ng1Expression): any;
31 $digest(): any;
32 $evalAsync(exp: Ng1Expression, locals?: any): void;
33 $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function;
34 $$childTail: IScope;
35 $$childHead: IScope;
36 $$nextSibling: IScope;
37 [key: string]: any;
38}
39
40declare interface IScope extends IRootScopeService {
41}
42
43declare type Ng1Expression = string | Function;
44
45/**
46 * Use `UpgradeAdapter` to allow AngularJS and Angular to coexist in a single application.
47 *
48 * The `UpgradeAdapter` allows:
49 * 1. creation of Angular component from AngularJS component directive
50 * (See [UpgradeAdapter#upgradeNg1Component()])
51 * 2. creation of AngularJS directive from Angular component.
52 * (See [UpgradeAdapter#downgradeNg2Component()])
53 * 3. Bootstrapping of a hybrid Angular application which contains both of the frameworks
54 * coexisting in a single application.
55 *
56 * @usageNotes
57 * ### Mental Model
58 *
59 * When reasoning about how a hybrid application works it is useful to have a mental model which
60 * describes what is happening and explains what is happening at the lowest level.
61 *
62 * 1. There are two independent frameworks running in a single application, each framework treats
63 * the other as a black box.
64 * 2. Each DOM element on the page is owned exactly by one framework. Whichever framework
65 * instantiated the element is the owner. Each framework only updates/interacts with its own
66 * DOM elements and ignores others.
67 * 3. AngularJS directives always execute inside AngularJS framework codebase regardless of
68 * where they are instantiated.
69 * 4. Angular components always execute inside Angular framework codebase regardless of
70 * where they are instantiated.
71 * 5. An AngularJS component can be upgraded to an Angular component. This creates an
72 * Angular directive, which bootstraps the AngularJS component directive in that location.
73 * 6. An Angular component can be downgraded to an AngularJS component directive. This creates
74 * an AngularJS directive, which bootstraps the Angular component in that location.
75 * 7. Whenever an adapter component is instantiated the host element is owned by the framework
76 * doing the instantiation. The other framework then instantiates and owns the view for that
77 * component. This implies that component bindings will always follow the semantics of the
78 * instantiation framework. The syntax is always that of Angular syntax.
79 * 8. AngularJS is always bootstrapped first and owns the bottom most view.
80 * 9. The new application is running in Angular zone, and therefore it no longer needs calls to
81 * `$apply()`.
82 *
83 * ### Example
84 *
85 * ```
86 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module), myCompilerOptions);
87 * const module = angular.module('myExample', []);
88 * module.directive('ng2Comp', adapter.downgradeNg2Component(Ng2Component));
89 *
90 * module.directive('ng1Hello', function() {
91 * return {
92 * scope: { title: '=' },
93 * template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
94 * };
95 * });
96 *
97 *
98 * @Component({
99 * selector: 'ng2-comp',
100 * inputs: ['name'],
101 * template: 'ng2[<ng1-hello [title]="name">transclude</ng1-hello>](<ng-content></ng-content>)',
102 * directives:
103 * })
104 * class Ng2Component {
105 * }
106 *
107 * @NgModule({
108 * declarations: [Ng2Component, adapter.upgradeNg1Component('ng1Hello')],
109 * imports: [BrowserModule]
110 * })
111 * class MyNg2Module {}
112 *
113 *
114 * document.body.innerHTML = '<ng2-comp name="World">project</ng2-comp>';
115 *
116 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
117 * expect(document.body.textContent).toEqual(
118 * "ng2[ng1[Hello World!](transclude)](project)");
119 * });
120 *
121 * ```
122 *
123 * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
124 * [Ahead-of-Time compilation](guide/aot-compiler).
125 * @publicApi
126 */
127export declare class UpgradeAdapter {
128 private ng2AppModule;
129 private compilerOptions?;
130 private idPrefix;
131 private downgradedComponents;
132 private upgradedProviders;
133 private ngZone;
134 private ng1Module;
135 private moduleRef;
136 private ng2BootstrapDeferred;
137 constructor(ng2AppModule: Type<any>, compilerOptions?: CompilerOptions | undefined);
138 /**
139 * Allows Angular Component to be used from AngularJS.
140 *
141 * Use `downgradeNg2Component` to create an AngularJS Directive Definition Factory from
142 * Angular Component. The adapter will bootstrap Angular component from within the
143 * AngularJS template.
144 *
145 * @usageNotes
146 * ### Mental Model
147 *
148 * 1. The component is instantiated by being listed in AngularJS template. This means that the
149 * host element is controlled by AngularJS, but the component's view will be controlled by
150 * Angular.
151 * 2. Even thought the component is instantiated in AngularJS, it will be using Angular
152 * syntax. This has to be done, this way because we must follow Angular components do not
153 * declare how the attributes should be interpreted.
154 * 3. `ng-model` is controlled by AngularJS and communicates with the downgraded Angular component
155 * by way of the `ControlValueAccessor` interface from @angular/forms. Only components that
156 * implement this interface are eligible.
157 *
158 * ### Supported Features
159 *
160 * - Bindings:
161 * - Attribute: `<comp name="World">`
162 * - Interpolation: `<comp greeting="Hello {{name}}!">`
163 * - Expression: `<comp [name]="username">`
164 * - Event: `<comp (close)="doSomething()">`
165 * - ng-model: `<comp ng-model="name">`
166 * - Content projection: yes
167 *
168 * ### Example
169 *
170 * ```
171 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
172 * const module = angular.module('myExample', []);
173 * module.directive('greet', adapter.downgradeNg2Component(Greeter));
174 *
175 * @Component({
176 * selector: 'greet',
177 * template: '{{salutation}} {{name}}! - <ng-content></ng-content>'
178 * })
179 * class Greeter {
180 * @Input() salutation: string;
181 * @Input() name: string;
182 * }
183 *
184 * @NgModule({
185 * declarations: [Greeter],
186 * imports: [BrowserModule]
187 * })
188 * class MyNg2Module {}
189 *
190 * document.body.innerHTML =
191 * 'ng1 template: <greet salutation="Hello" [name]="world">text</greet>';
192 *
193 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
194 * expect(document.body.textContent).toEqual("ng1 template: Hello world! - text");
195 * });
196 * ```
197 */
198 downgradeNg2Component(component: Type<any>): Function;
199 /**
200 * Allows AngularJS Component to be used from Angular.
201 *
202 * Use `upgradeNg1Component` to create an Angular component from AngularJS Component
203 * directive. The adapter will bootstrap AngularJS component from within the Angular
204 * template.
205 *
206 * @usageNotes
207 * ### Mental Model
208 *
209 * 1. The component is instantiated by being listed in Angular template. This means that the
210 * host element is controlled by Angular, but the component's view will be controlled by
211 * AngularJS.
212 *
213 * ### Supported Features
214 *
215 * - Bindings:
216 * - Attribute: `<comp name="World">`
217 * - Interpolation: `<comp greeting="Hello {{name}}!">`
218 * - Expression: `<comp [name]="username">`
219 * - Event: `<comp (close)="doSomething()">`
220 * - Transclusion: yes
221 * - Only some of the features of
222 * [Directive Definition Object](https://docs.angularjs.org/api/ng/service/$compile) are
223 * supported:
224 * - `compile`: not supported because the host element is owned by Angular, which does
225 * not allow modifying DOM structure during compilation.
226 * - `controller`: supported. (NOTE: injection of `$attrs` and `$transclude` is not supported.)
227 * - `controllerAs`: supported.
228 * - `bindToController`: supported.
229 * - `link`: supported. (NOTE: only pre-link function is supported.)
230 * - `name`: supported.
231 * - `priority`: ignored.
232 * - `replace`: not supported.
233 * - `require`: supported.
234 * - `restrict`: must be set to 'E'.
235 * - `scope`: supported.
236 * - `template`: supported.
237 * - `templateUrl`: supported.
238 * - `terminal`: ignored.
239 * - `transclude`: supported.
240 *
241 *
242 * ### Example
243 *
244 * ```
245 * const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
246 * const module = angular.module('myExample', []);
247 *
248 * module.directive('greet', function() {
249 * return {
250 * scope: {salutation: '=', name: '=' },
251 * template: '{{salutation}} {{name}}! - <span ng-transclude></span>'
252 * };
253 * });
254 *
255 * module.directive('ng2', adapter.downgradeNg2Component(Ng2Component));
256 *
257 * @Component({
258 * selector: 'ng2',
259 * template: 'ng2 template: <greet salutation="Hello" [name]="world">text</greet>'
260 * })
261 * class Ng2Component {
262 * }
263 *
264 * @NgModule({
265 * declarations: [Ng2Component, adapter.upgradeNg1Component('greet')],
266 * imports: [BrowserModule]
267 * })
268 * class MyNg2Module {}
269 *
270 * document.body.innerHTML = '<ng2></ng2>';
271 *
272 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
273 * expect(document.body.textContent).toEqual("ng2 template: Hello world! - text");
274 * });
275 * ```
276 */
277 upgradeNg1Component(name: string): Type<any>;
278 /**
279 * Registers the adapter's AngularJS upgrade module for unit testing in AngularJS.
280 * Use this instead of `angular.mock.module()` to load the upgrade module into
281 * the AngularJS testing injector.
282 *
283 * @usageNotes
284 * ### Example
285 *
286 * ```
287 * const upgradeAdapter = new UpgradeAdapter(MyNg2Module);
288 *
289 * // configure the adapter with upgrade/downgrade components and services
290 * upgradeAdapter.downgradeNg2Component(MyComponent);
291 *
292 * let upgradeAdapterRef: UpgradeAdapterRef;
293 * let $compile, $rootScope;
294 *
295 * // We must register the adapter before any calls to `inject()`
296 * beforeEach(() => {
297 * upgradeAdapterRef = upgradeAdapter.registerForNg1Tests(['heroApp']);
298 * });
299 *
300 * beforeEach(inject((_$compile_, _$rootScope_) => {
301 * $compile = _$compile_;
302 * $rootScope = _$rootScope_;
303 * }));
304 *
305 * it("says hello", (done) => {
306 * upgradeAdapterRef.ready(() => {
307 * const element = $compile("<my-component></my-component>")($rootScope);
308 * $rootScope.$apply();
309 * expect(element.html()).toContain("Hello World");
310 * done();
311 * })
312 * });
313 *
314 * ```
315 *
316 * @param modules any AngularJS modules that the upgrade module should depend upon
317 * @returns an `UpgradeAdapterRef`, which lets you register a `ready()` callback to
318 * run assertions once the Angular components are ready to test through AngularJS.
319 */
320 registerForNg1Tests(modules?: string[]): UpgradeAdapterRef;
321 /**
322 * Bootstrap a hybrid AngularJS / Angular application.
323 *
324 * This `bootstrap` method is a direct replacement (takes same arguments) for AngularJS
325 * [`bootstrap`](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method. Unlike
326 * AngularJS, this bootstrap is asynchronous.
327 *
328 * @usageNotes
329 * ### Example
330 *
331 * ```
332 * const adapter = new UpgradeAdapter(MyNg2Module);
333 * const module = angular.module('myExample', []);
334 * module.directive('ng2', adapter.downgradeNg2Component(Ng2));
335 *
336 * module.directive('ng1', function() {
337 * return {
338 * scope: { title: '=' },
339 * template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
340 * };
341 * });
342 *
343 *
344 * @Component({
345 * selector: 'ng2',
346 * inputs: ['name'],
347 * template: 'ng2[<ng1 [title]="name">transclude</ng1>](<ng-content></ng-content>)'
348 * })
349 * class Ng2 {
350 * }
351 *
352 * @NgModule({
353 * declarations: [Ng2, adapter.upgradeNg1Component('ng1')],
354 * imports: [BrowserModule]
355 * })
356 * class MyNg2Module {}
357 *
358 * document.body.innerHTML = '<ng2 name="World">project</ng2>';
359 *
360 * adapter.bootstrap(document.body, ['myExample']).ready(function() {
361 * expect(document.body.textContent).toEqual(
362 * "ng2[ng1[Hello World!](transclude)](project)");
363 * });
364 * ```
365 */
366 bootstrap(element: Element, modules?: any[], config?: IAngularBootstrapConfig): UpgradeAdapterRef;
367 /**
368 * Allows AngularJS service to be accessible from Angular.
369 *
370 * @usageNotes
371 * ### Example
372 *
373 * ```
374 * class Login { ... }
375 * class Server { ... }
376 *
377 * @Injectable()
378 * class Example {
379 * constructor(@Inject('server') server, login: Login) {
380 * ...
381 * }
382 * }
383 *
384 * const module = angular.module('myExample', []);
385 * module.service('server', Server);
386 * module.service('login', Login);
387 *
388 * const adapter = new UpgradeAdapter(MyNg2Module);
389 * adapter.upgradeNg1Provider('server');
390 * adapter.upgradeNg1Provider('login', {asToken: Login});
391 *
392 * adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
393 * const example: Example = ref.ng2Injector.get(Example);
394 * });
395 *
396 * ```
397 */
398 upgradeNg1Provider(name: string, options?: {
399 asToken: any;
400 }): void;
401 /**
402 * Allows Angular service to be accessible from AngularJS.
403 *
404 * @usageNotes
405 * ### Example
406 *
407 * ```
408 * class Example {
409 * }
410 *
411 * const adapter = new UpgradeAdapter(MyNg2Module);
412 *
413 * const module = angular.module('myExample', []);
414 * module.factory('example', adapter.downgradeNg2Provider(Example));
415 *
416 * adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
417 * const example: Example = ref.ng1Injector.get('example');
418 * });
419 *
420 * ```
421 */
422 downgradeNg2Provider(token: any): Function;
423 /**
424 * Declare the AngularJS upgrade module for this adapter without bootstrapping the whole
425 * hybrid application.
426 *
427 * This method is automatically called by `bootstrap()` and `registerForNg1Tests()`.
428 *
429 * @param modules The AngularJS modules that this upgrade module should depend upon.
430 * @returns The AngularJS upgrade module that is declared by this method
431 *
432 * @usageNotes
433 * ### Example
434 *
435 * ```
436 * const upgradeAdapter = new UpgradeAdapter(MyNg2Module);
437 * upgradeAdapter.declareNg1Module(['heroApp']);
438 * ```
439 */
440 private declareNg1Module;
441}
442
443/**
444 * Use `UpgradeAdapterRef` to control a hybrid AngularJS / Angular application.
445 *
446 * @deprecated Deprecated since v5. Use `upgrade/static` instead, which also supports
447 * [Ahead-of-Time compilation](guide/aot-compiler).
448 * @publicApi
449 */
450export declare class UpgradeAdapterRef {
451 ng1RootScope: IRootScopeService;
452 ng1Injector: IInjectorService;
453 ng2ModuleRef: NgModuleRef<any>;
454 ng2Injector: Injector;
455 /**
456 * Register a callback function which is notified upon successful hybrid AngularJS / Angular
457 * application has been bootstrapped.
458 *
459 * The `ready` callback function is invoked inside the Angular zone, therefore it does not
460 * require a call to `$apply()`.
461 */
462 ready(fn: (upgradeAdapterRef: UpgradeAdapterRef) => void): void;
463 /**
464 * Dispose of running hybrid AngularJS / Angular application.
465 */
466 dispose(): void;
467}
468
469/**
470 * @publicApi
471 */
472export declare const VERSION: Version;
473
474export { }