AngularDart

https://pub.dev/documentation/ngdart/latest/
Admin
AngularDart is an open-source web framework built on Dart that emphasizes productivity, performance,...
Tokens:110,647
Snippets:1,256
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Using a Type selector

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChildren-class.html

This example demonstrates how to use ViewChildren with a Type selector to get a list of `ChildCmp` instances.

```APIDOC
## Example: Using a Type selector

### Description
This example shows how to query for multiple instances of a `ChildCmp` directive using its type.

### Component Usage
```dart
@Component(
  selector: 'some-cmp',
  template: '''
    <child-cmp></child-cmp>
    <child-cmp></child-cmp>
    <child-cmp></child-cmp>
  ''',
  directives: [ChildCmp],
)
class SomeCmp implements AfterViewInit {
  @ViewChildren(ChildCmp)
  List<ChildCmp> children;

  @override
  void ngAfterViewInit() {
    // children are set
    for (var child in children) {
      child.doSomething();
    }
  }
}
```
```

--------------------------------

### Example InjectorFactory Implementation

Source: https://pub.dev/documentation/ngdart/latest/di/InjectorFactory.html

Demonstrates how to create a concrete InjectorFactory function that provides an 'Example' service. This function takes a parent injector and returns a new injector configured with the 'Example' service.

```dart
class Example {}

/// Returns an [Injector] that provides an `Example` service.
Injector createInjector(Injector parent) {
  return Injector.map({
    Example: Example(),
  }, parent);
}

void main() {
  var injector = createInjector();
  print(injector.get(Example)); // 'Instance of Example'.
}

```

--------------------------------

### SlicePipe String Slicing Examples

Source: https://pub.dev/documentation/ngdart/latest/angular/SlicePipe-class.html

Illustrates various string slicing scenarios using the SlicePipe with different start and end index combinations, including positive, negative, and out-of-bounds indices.

```html
<pre>
  {{str}}[0:4]:   '$pipe.slice(str, 0, 4)}}' --> 'abcd'
  {{str}}[4:0]:   '$pipe.slice(str, 4, 0)}}' --> ''
  {{str}}[-4]:    '$pipe.slice(str, -4)}}' --> 'ghij'
  {{str}}[-4:-2]: '$pipe.slice(str, -4, -2)}}' --> 'gh'
  {{str}}[-100]:  '$pipe.slice(str, -100)}}' --> 'abcdefghij'
  {{str}}[100]:   '$pipe.slice(str, 100)}}' --> ''
</pre>
```

--------------------------------

### MultiToken Usage Example

Source: https://pub.dev/documentation/ngdart/latest/di/MultiToken-class.html

Demonstrates how to create and use a MultiToken for dependency injection with multiple values.

```APIDOC
## MultiToken Usage Example

### Description
This example shows how to define a MultiToken for strings representing US presidents and inject them into a component.

### Code
```dart
// Define a const MultiToken for US Presidents
const usPresidents = const MultiToken<String>('usPresidents');

// Component that injects the list of presidents
@Component(
  selector: 'presidents-list',
  providers: const [
    // Provide multiple values for the usPresidents token
    const ValueProvider.forToken(usPresidents, 'George Washington'),
    const ValueProvider.forToken(usPresidents, 'Abraham Lincoln'),
  ],
)
class PresidentsListComponent {
  // The items will be ['George Washington', 'Abraham Lincoln']
  final List<String> items;

  PresidentsListComponent(@Inject(usPresidents) this.items);
}
```
```

--------------------------------

### Example: Reading an HTML element using `read`

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChildren-class.html

This example demonstrates how to use the `read` parameter with ViewChildren to access the underlying HTML `Element` of the child components.

```APIDOC
## Example: Reading an HTML element using `read`

### Description
This example shows how to use the `read` parameter with `ViewChildren` to obtain the native HTML `Element` instances of the queried child components.

### Component Usage
```dart
@Component(
  selector: 'some-cmp',
  template: '''
    <child-cmp #child1></child-cmp>
    <child-cmp #child2></child-cmp>
    <child-cmp #child3></child-cmp>
  ''',
  directives: [ChildCmp],
)
class SomeCmp {
  @ViewChildren('child1, child2, child3', read: Element)
  List<Element> children;
}
```
```

--------------------------------

### Example Usage with ReflectiveInjector

Source: https://pub.dev/documentation/ngdart/latest/di/FactoryProvider-class.html

Demonstrates how to use FactoryProvider with ReflectiveInjector to resolve and create dependencies, including specifying factory function dependencies.

```APIDOC
## Example Usage with ReflectiveInjector

### Description
This example shows how to configure a `FactoryProvider` for a `Foo` class that depends on a `Bar` class, using `ReflectiveInjector.resolveAndCreate`.

### Code
```dart
import 'package:injectable/injectable.dart';

class Bar {}

class Foo {
  Foo(this.bar);
  final Bar bar;
}

// Assuming Foo and Bar are defined elsewhere
final injector = ReflectiveInjector.resolveAndCreate([
  FactoryProvider(Foo, (Bar bar) => new Foo(bar), deps: [Bar]),
  bind(Bar).toFactory((i) => Bar())
]);

final fooInstance = injector.get(Foo);
```

### Notes
- For static forms of injection (compile-time), the `deps` argument is not required.
- When using `ReflectiveInjector`, `deps` is required unless the factory function has no arguments.
```

--------------------------------

### Example: Using a String selector

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChildren-class.html

This example shows how to use ViewChildren with a String selector to target elements with specific template variables.

```APIDOC
## Example: Using a String selector

### Description
This example demonstrates querying for child components using template variable names specified as a comma-separated string.

### Component Usage
```dart
@Component(
  selector: 'some-cmp',
  template: '''
    <child-cmp #child1></child-cmp>
    <child-cmp #child2></child-cmp>
    <child-cmp #child3></child-cmp>
  ''',
  directives: [ChildCmp],
)
class SomeCmp implements AfterViewInit {
  @ViewChildren('child1, child2, child3')
  List<ChildCmp> children;

  @override
  void ngAfterViewInit() {
    // Initial children are set
    for (var child in children) {
      child.doSomething();
    }
  }
}
```
```

--------------------------------

### Example Usage of provideToken with MultiToken

Source: https://pub.dev/documentation/ngdart/latest/di/Injector/provideToken.html

Demonstrates how provideToken works with a MultiToken. The `identical` check returns false, indicating that a new List instance is created for each invocation when using MultiToken.

```dart
const usPresidents = MultiToken<String>('usPresidents');

void example(Injector i) {
  final a = i.provideToken(usPresidents);
  final b = i.provideToken(usPresidents);
  print(identical(a, b)); // false
}
```

--------------------------------

### AsyncPipe Usage Example

Source: https://pub.dev/documentation/ngdart/latest/angular/AsyncPipe-class.html

Demonstrates how to use the AsyncPipe in Angular templates to display data from a Future or Stream.

```APIDOC
## AsyncPipe

An `async` pipe awaits for a value from a Future or Stream. When a value is received, the `async` pipe marks the component to be checked for changes.

### Example

```dart
@Component(
    selector: 'async-greeter',
    template: '''
      <div>
        <p>Wait for it ... {{ $pipe.async(greeting) }}</p>
        <button [disabled]="!done" (click)="tryAgain()">Try Again!</button>
      </div>''')
class AsyncGreeterPipe {
  static const _delay = const Duration(seconds: 2);

  Future<String> greeting;
  bool done;

  AsyncGreeterPipe() {
    tryAgain();
  }

  String greet() {
    done = true;
    return "Hi!";
  }

  void tryAgain() {
    done = false;
    greeting = new Future<String>.delayed(_delay, greet);
  }
}

@Component(
    selector: 'async-time',
    template: "<p>Time: {{ $pipe.date($pipe.async(time), 'mediumTime') }}</p>") //
class AsyncTimePipe {
  static const _delay = const Duration(seconds: 1);
  final Stream<DateTime> time =
      new Stream.periodic(_delay, (_) => new DateTime.now());
}
```

### Constructors

`AsyncPipe(ChangeDetectorRef _ref)`

### Methods

`transform(dynamic obj)`

This method is the core of the AsyncPipe, transforming an observable or promise into a stream of values.
```

--------------------------------

### Previous module definition pattern

Source: https://pub.dev/documentation/ngdart/latest/di/Module-class.html

Illustrates the older pattern for defining modules as a recursive list of providers, before the introduction of the Module class. This is the 'Before' example.

```dart
// Before.
const carModule = [
  ClassProvider(Car, useClass: AmericanCar),
];

const autoShopModule = [
  carModule,
  ClassProvider(Oil, useClass: GenericOil),
];
```

--------------------------------

### Host Binding Examples

Source: https://pub.dev/documentation/ngdart/latest/angular/HostBinding-class.html

These bindings are similar to using template syntax for properties or attributes and are automatically updated when the referenced class member changes.

```dart
@Directive(...)
class HostBindingExample {
  // Similar to <example [value]="hostValue"> in a template.
  @HostBinding('value')
  String hostValue;

  // Similar to <example [attr.debug-id]="debugId"> in a template.
  @HostBinding('attr.debug-id')
  String debugId;
}
```

--------------------------------

### ngAfterViewInit()

Source: https://pub.dev/documentation/ngdart/latest/angular/AfterViewInit-class.html

This method is called once after the component's view (and its children's views) has been fully initialized. It's a suitable place to perform setup tasks that rely on the view being present and interactive.

```APIDOC
## ngAfterViewInit()

### Description
Callback method that is invoked immediately after the default change detector has completed a check of the component's view.

### Method
```dart
void ngAfterViewInit()
```

### Parameters
This method does not accept any parameters.

### Response
This method does not return any value.
```

--------------------------------

### Example: Using a setter for update notifications

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChildren-class.html

This example illustrates using a setter with ViewChildren to receive notifications whenever the list of visible children changes, especially useful with dynamic content like `*ngIf`.

```APIDOC
## Example: Using a setter for update notifications

### Description
This example shows how to use a setter to react to changes in the queried child components, which is particularly useful when child components are conditionally rendered.

### Component Usage
```dart
@Component(
  selector: 'some-cmp',
  template: '''
    <child-cmp *ngIf="condition1" #child1></child-cmp>
    <child-cmp *ngIf="condition2" #child2></child-cmp>
    <child-cmp *ngIf="condition3" #child3></child-cmp>
  ''',
  directives: [ChildCmp],
)
class SomeCmp {
  @Input()
  bool condition1 = false;

  @Input()
  bool condition2 = false;

  @Input()
  bool condition3 = false;

  @ViewChildren('child1, child2, child3')
  set children(List<ChildCmp> children) {
    // Note above that the child components may or may not be created (they
    // are guarded with '*ngIf'). This setter is called every time the
    // visible children change (including the initial visibility, so we do
    // not need 'ngAfterViewInit').
    for (var child in children) {
      child.doSomething();
    }
  }
}
```
```

--------------------------------

### SlicePipe Usage Example

Source: https://pub.dev/documentation/ngdart/latest/angular/SlicePipe-class.html

Demonstrates how to use the SlicePipe to iterate over a subset of a list. The pipe extracts elements from index 1 up to (but not including) index 3.

```html
<ul>
    <li *ngFor="let i of $pipe.slice(['a', 'b', 'c', 'd'], 1, 3)">{{i}}</li>
</ul>
```

--------------------------------

### Implementation of provideToken Method

Source: https://pub.dev/documentation/ngdart/latest/di/Injector/provideToken.html

The core implementation of the provideToken method, which retrieves an object instance using `get` and performs an unsafe cast to the expected type.

```dart
@nonVirtual
T provideToken<T extends Object>(OpaqueToken<T> token) {
  return unsafeCast(get(token));
}
```

--------------------------------

### Component Definition Example

Source: https://pub.dev/documentation/ngdart/latest/angular/ComponentFactory-class.html

Defines a component using the @Component annotation. This serves as the source for a generated ComponentFactory.

```dart
@Component(
  selector: 'example',
  template: '...',
)
class Example {}

```

--------------------------------

### Component with Input Properties

Source: https://pub.dev/documentation/ngdart/latest/di/Input-class.html

This example demonstrates how to create a component with two input properties, one using the default property name and another specifying a custom binding property name for template instantiation.

```dart
@Component(
   selector: 'bank-account',
   template: '''
     Bank Name: {{bankName}}
     Account Id: {{id}}
   ''')
 class BankAccount {
   @Input()
   String bankName;

   @Input('account-id')
   String id;

   // this property is not bound, and won't be automatically updated
   String normalizedBankName;
 }

 @Component(
   selector: 'app',
   template: '''
     <bank-account bank-name="RBC" account-id="4747"></bank-account>
   ''',
   directives: const [BankAccount])
 class App {}

```

--------------------------------

### Basic runApp Usage

Source: https://pub.dev/documentation/ngdart/latest/angular/runApp.html

Starts a new AngularDart application with a specified component factory. Ensure the component factory is correctly imported and generated.

```dart
import 'package:ngdart/angular.dart';
import 'main.template.dart' as ng;

@Component(
  selector: 'hello-world',
  template: '',
)
class HelloWorld {}

void main() {
  runApp(ng.HelloWorldNgFactory);
}
```

--------------------------------

### Module class for dependency injection

Source: https://pub.dev/documentation/ngdart/latest/di/Module-class.html

Defines a module for dependency injection, including other modules and providers. This is the 'After' example, demonstrating the use of the Module class.

```dart
const carModule = Module(
  provide: [
    ClassProvider(Car, useClass: AmericanCar),
  ],
);

const autoShopModule = Module(
  include: [
    carModule,
  ],
  provide: [
    ClassProvider(Oil, useClass: GenericOil),
  ],
);
```

--------------------------------

### ViewChild Usage Example

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChild-class.html

Demonstrates how to use the @ViewChild annotation to get a reference to a child component. The child component must be declared in the template of the parent component.

```dart
@Component(
  selector: 'child-cmp',
  template: '<p>child</p>',
)
class ChildCmp {}

@Component(
  selector: 'some-cmp',
  template: '<child-cmp></child-cmp>',
  directives: [ChildCmp],
)
class SomeCmp {
  @ViewChild(ChildCmp)
  ChildCmp child;
}

```

--------------------------------

### Example HTML for Directive Selection

Source: https://pub.dev/documentation/ngdart/latest/di/Directive/selector.html

This HTML demonstrates a scenario where a directive with an input[type=text] selector would be applied. Only the input element matching the selector will trigger the directive.

```html
<form>
  <input type="text">
  <input type="radio">
<form>
```

--------------------------------

### Using SkipSelf Annotation for Dependency Resolution

Source: https://pub.dev/documentation/ngdart/latest/di/SkipSelf-class.html

Demonstrates how to use the @SkipSelf() annotation to inject a dependency from a parent injector. This example shows the setup for a child injector resolving a dependency provided by its parent, and also includes a case where the dependency is not found in the parent.

```dart
class Dependency {}

@Injectable()
class NeedsDependency {
  final Dependency dependency;
  NeedsDependency(@SkipSelf() this.dependency);
}

var parent = Injector.resolveAndCreate([Dependency]);
var child = parent.resolveAndCreateChild([NeedsDependency]);
expect(child.get(NeedsDependency).dependency, new
    isInstanceOf<Dependency>());

var inj = Injector.resolveAndCreate([Dependency, NeedsDependency]);
expect(() => inj.get(NeedsDependency), throws);
```

--------------------------------

### Self Annotation Example

Source: https://pub.dev/documentation/ngdart/latest/di/Self-class.html

Example demonstrating the usage of the @Self() annotation in a class constructor to inject a dependency.

```APIDOC
## Example Usage

### Description
This example shows how to use the `@Self()` annotation to ensure a dependency is provided by the current injector.

### Code
```dart
class Dependency {}

@Injectable()
class NeedsDependency {
  final Dependency dependency;
  NeedsDependency(@Self() this.dependency);
}

var inj = Injector.resolveAndCreate([Dependency, NeedsDependency]);
var nd = inj.get(NeedsDependency);

expect(nd.dependency, new isInstanceOf<Dependency>());

// Example demonstrating scope restriction
inj = Injector.resolveAndCreate([Dependency]);
var child = inj.resolveAndCreateChild([NeedsDependency]);
expect(() => child.get(NeedsDependency), throws);
```
```

--------------------------------

### NgZone onTurnStart Stream Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/NgZone/onTurnStart.html

This code shows how the onTurnStart stream is implemented, exposing a stream that emits void events.

```dart
Stream<void> get onTurnStart => _onTurnStart.stream;
```

--------------------------------

### Basic Usage of HostListener

Source: https://pub.dev/documentation/ngdart/latest/angular/HostListener-class.html

Demonstrates how to use the @HostListener decorator to listen for a 'click' event on the host element and execute a method.

```APIDOC
## @HostListener('click')
void onClick() {}

### Description
Listens for the 'click' event on the host element.

### Method Signature
`void onClick()`
```

--------------------------------

### ContentChildren Example

Source: https://pub.dev/documentation/ngdart/latest/angular/ContentChildren-class.html

Example demonstrating the usage of the ContentChildren decorator in an Angular Dart component to query for child components.

```APIDOC
## Example Usage

```dart
@Component(
  selector: 'tab-panel',
  template: '<ng-content></ng-content>',
)
class TabPanelComponent implements AfterContentInit {
  @ContentChildren(TabComponent)
  List<TabComponent> tabs;

  @override
  void ngAfterContentInit() {
    for (var tab in tabs) {
      // Do something with each tab component.
    }
  }
}
```
```

--------------------------------

### Attribute Usage Example

Source: https://pub.dev/documentation/ngdart/latest/angular/Attribute-class.html

Example demonstrating how to use the @Attribute annotation in a directive to inject an element's attribute value.

```APIDOC
## Example

Suppose we have an `<input>` element and want to know its `type`.

```html
<input type="text">
```

A Directive could read the string literal `'text'` like so:

```dart
@Directive(selector: 'input')
class InputAttrDirective {
  InputAttrDirective(@Attribute('type') String type) {
    print(type); // 'text'
  }
}
```
```

--------------------------------

### Injector get method implementation

Source: https://pub.dev/documentation/ngdart/latest/di/Injector/get.html

This is the internal implementation of the `get` method, which handles error checking and calls the underlying provider.

```dart
@mustCallSuper
dynamic get(
  Object token, [
  Object? notFoundValue = throwIfNotFound,
]) {
  errors.debugInjectorEnter(token);
  final result = provideUntyped(token, notFoundValue);
  if (identical(result, throwIfNotFound)) {
    throw errors.noProviderError(token);
  }
  errors.debugInjectorLeave(token);
  return result;
}
```

--------------------------------

### Host Constructor

Source: https://pub.dev/documentation/ngdart/latest/di/Host/Host.html

Provides information on how to create a new instance of the Host class using its const constructor.

```APIDOC
## Host constructor 

```dart
const Host()
```

### Description

This is a constant constructor for the Host class. It allows for the creation of immutable Host objects.

### Method

`const Host()`

### Parameters

This constructor does not take any parameters.
```

--------------------------------

### bootstrap

Source: https://pub.dev/documentation/ngdart/latest/angular/ApplicationRef-class.html

Bootstrap a new component at the root level of the application.

```APIDOC
## bootstrap<T extends Object>(ComponentFactory<T> componentFactory)

### Description
Bootstrap a new component at the root level of the application.

### Method
bootstrap

### Parameters
#### Path Parameters
- **componentFactory** (ComponentFactory<T>) - Required - The factory for the component to bootstrap.
```

--------------------------------

### Visibility.local - Providing Interface via ExistingProvider

Source: https://pub.dev/documentation/ngdart/latest/angular/Visibility.html

Illustrates how to provide an interface to child components using `ExistingProvider` with `Visibility.local` on the parent.

```dart
// An interface that will be provided by the Parent class.
abstract class Example {}

@Component(
  selector: 'parent',
  directives: const [Child],
  providers: const [
    const ExistingProvider(Example, useExisting: Parent),
  ],
  template: '<child></child>',
)

class Parent implements Example {}
@Component( selector: 'child', template: '', ) class Child { // Fine! Child(Example example); }

```

--------------------------------

### OpaqueToken Usage

Source: https://pub.dev/documentation/ngdart/latest/di/OpaqueToken-class.html

Demonstrates how to create and use an OpaqueToken for dependency injection, including providing a value for the token.

```APIDOC
## OpaqueToken Usage

### Description
This example shows how to declare a constant OpaqueToken and provide a value for it using `ValueProvider.forToken` within a component's providers.

### Code
```dart
const loginUrl = const OpaqueToken<String>('loginUrl');

@Component(
  selector: 'dashboard',
  providers: const [
    const ValueProvider.forToken(loginUrl, 'https://someurl.com'),
  ],
)
class DashboardComponent {}
```
```

--------------------------------

### Example Usage of OnDestroy

Source: https://pub.dev/documentation/ngdart/latest/angular/OnDestroy-class.html

This example demonstrates how to implement the OnDestroy interface in an AngularDart component. The ngOnDestroy method is used to cancel a StreamSubscription, ensuring that no memory leaks occur when the component is destroyed.

```dart
@Component(
  selector: 'user-panel',
  template: 'Online users: {{count}}',
)
class UserPanel implements OnInit, OnDestroy {
  StreamSubscription _onlineUserSub;

  int count = 0;

  @override
  void ngOnInit() {
    _onlineUserSub = onlineUsers.listen((count) => this.count = count);
  }

  @override
  void ngOnDestroy() {
    _onlineUserSub.cancel();
  }
}

```

--------------------------------

### ViewRef get(int index)

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/get.html

Returns the view located in this container at the specified `index`.

```APIDOC
## get

### Description
Returns the view located in this container at the specified `index`.

### Method Signature
ViewRef get(int index)

### Parameters
#### Path Parameters
* **index** (int) - Required - The index of the view to retrieve.
```

--------------------------------

### HostListener with Event Arguments

Source: https://pub.dev/documentation/ngdart/latest/angular/HostListener-class.html

Shows how to use @HostListener to capture event arguments, including the special '$event' argument, which is automatically passed to the method.

```APIDOC
## @HostListener('click')
void onClick(MouseEvent e) {}

### Description
Listens for the 'click' event and passes the MouseEvent object to the onClick method.

### Method Signature
`void onClick(MouseEvent e)`
```

--------------------------------

### ComponentFactory.create Method Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/ComponentFactory/create.html

This is the implementation of the `create` method. It generates a host view and then creates the component using the provided `projectableNodes` and `injector`. Use with caution if `projectableNodes` is provided.

```dart
ComponentRef<T> create(
  Injector injector, [
  List<List<Object>>? projectableNodes,
]) {
  final hostView = _viewFactory();
  return hostView.create(projectableNodes ?? const [], injector);
}
```

--------------------------------

### ViewChild Annotation Usage

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewChild-class.html

Demonstrates how to use the @ViewChild annotation to get a reference to a child component.

```APIDOC
## @ViewChild Annotation

### Description
Declares a reference to a single child node in a component's template. This annotation is semantically similar to ViewChildren, but it represents a single (or the first, if more than one is found) node being queried, akin to `querySelector` instead of `querySelectorAll`.

### Example Usage

```dart
@Component(
  selector: 'child-cmp',
  template: '<p>child</p>',
)
class ChildCmp {}

@Component(
  selector: 'some-cmp',
  template: '<child-cmp></child-cmp>',
  directives: [ChildCmp],
)
class SomeCmp {
  @ViewChild(ChildCmp)
  ChildCmp child;
}
```

### Constructor

`ViewChild(Object selector, {Object? read})`

### Properties

- `descendants` (bool): Whether to query only direct children (`false`) or all children (`true`).
- `first` (bool): Whether to only query the first child.
- `read` (Object?): The DI token to read from an element that matches the selector.
- `selector` (Object): Either the class Type or selector String.
```

--------------------------------

### Implement ApplicationRef.run Method

Source: https://pub.dev/documentation/ngdart/latest/angular/ApplicationRef/run.html

This implementation shows how the `run` method executes a callback, handles both synchronous and asynchronous exceptions, and manages the result, whether it's a synchronous value or a Future. It includes detailed comments on null-safety considerations and exception handling.

```dart
FutureOr<R> run<R>(FutureOr<R> Function() callback) {
  // Run the users callback, and handle uncaught exceptions.
  //
  // **NOTE**: It might be tempting to try and optimize this, but this is
  // required otherwise tests timeout - the completer needs to be created
  // outside as Dart swallows rejected futures outside the 'onError: '
  // callback for Future.
  final completer = Completer<R>();
  FutureOr<R>? result;
  runInZone(() {
    try {
      result = callback();
      if (result is Future<Object>) {
        final resultCast = unsafeCast<Future<R>>(result);
        resultCast.then((result) {
          completer.complete(result);
        }, onError: (e, s) {
          final sCasted = unsafeCast<StackTrace>(s);
          final eCasted = unsafeCast<Object>(e);
          completer.completeError(eCasted, sCasted);
          handleUncaughtException(eCasted, sCasted);
        });
      }
    } catch (e, s) {
      handleUncaughtException(e, s);
      // Note, due to the rethrow a synchronous error thrown in callback will
      // cause the `run` function never to return. This is important to note
      // because of the handling logic below.
      rethrow;
    }
  });
  // Some complexity in null-safety: `FutureOr<R>` can mean:
  // 1. Future<R> where R might be nullable or non-nullable.
  // 2. R, where R is non-nullable.
  // 3. R, where R is nullable.
  //
  // We need to carefully evaluate the three different cases to avoid a subtle
  // breaking API change (we still want our users to be allowed to return null
  // if they expect a nullable value) - i.e.:
  //
  //   // Should continue to be valid.
  //   String? name = run(() => null);
  //
  // See also: https://dart.dev/null-safety/understanding-null-safety#nullability-and-generics.
  final r = result;
  if (r == null) {
    // The variable r can only be null here if the callback returned null,
    // which in turn can only happen if either we were called from opted-in
    // code and R is nullable, or if we were called from opted-out code.
    //
    // In either case, the case here should always suceed. By explicitly
    // checking for null, we avoid having a cast in the final (and likely more
    // frequently executed) branch of the conditional.
    return r as R;
  } else if (r is Future<Object>) {
    // Return as a Future<R>.
    return completer.future;
  } else {
    // Return as R.
    return r;
  }
}
```

--------------------------------

### Basic MultiToken Usage

Source: https://pub.dev/documentation/ngdart/latest/di/MultiToken-class.html

Demonstrates creating a MultiToken for strings and injecting a list of values into a component. Ensure `ValueProvider.forToken` is used to associate values with the token.

```dart
const usPresidents = const MultiToken<String>('usPresidents');

@Component(
  selector: 'presidents-list',
  providers: const [
    const ValueProvider.forToken(usPresidents, 'George Washington'),
    const ValueProvider.forToken(usPresidents, 'Abraham Lincoln'),
  ],
)
class PresidentsListComponent {
  // Will be ['George Washington', 'Abraham Lincoln'].
  final List<String> items;

  PresidentsListComponent(@Inject(usPresidents) this.items);
}
```

--------------------------------

### runAppLegacyAsync

Source: https://pub.dev/documentation/ngdart/latest/angular/runAppLegacyAsync.html

Starts a new AngularDart application with `componentType` as the root. This is the runAppLegacy variant of the runAppAsync function.

```APIDOC
## runAppLegacyAsync<T extends Object>

### Description
Starts a new AngularDart application with `componentType` as the root. This is the runAppLegacy variant of the runAppAsync function.

### Signature
Future<ComponentRef<T>> runAppLegacyAsync<T extends Object>(
  Type componentType,
  {
  required Future<void> beforeComponentCreated(Injector),
  List<Object> createInjectorFromProviders = const [],
  void initReflector()?
}
)
```

--------------------------------

### runApp Implementation Details

Source: https://pub.dev/documentation/ngdart/latest/angular/runApp.html

The internal implementation of the runApp function, showing how it creates an injector, obtains an ApplicationRef, and bootstraps the root component.

```dart
ComponentRef<T> runApp<T extends Object>(
  ComponentFactory<T> componentFactory,
  {
  InjectorFactory createInjector = _identityInjector,
}) {
  final injector = appInjector(createInjector);
  final appRef = injector.provideType<ApplicationRef>(ApplicationRef);
  return appRef.bootstrap(componentFactory);
}
```

--------------------------------

### runAppAsync Function Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/runAppAsync.html

This is the implementation of the runAppAsync function. It takes a component factory, an asynchronous callback to run before component creation, and an optional injector factory. The callback is awaited before bootstrapping the root component.

```dart
Future<ComponentRef<T>> runAppAsync<T extends Object>(
  ComponentFactory<T> componentFactory, {
  required Future<void> Function(Injector) beforeComponentCreated,
  InjectorFactory createInjector = _identityInjector,
}) {
  final injector = appInjector(createInjector);
  final appRef = injector.provideType<ApplicationRef>(ApplicationRef);
  final ngZone = injector.provideType<NgZone>(NgZone);
  return ngZone.run(() {
    final future = beforeComponentCreated(injector);
    return future.then((_) => appRef.bootstrap(componentFactory));
  });
}
```

--------------------------------

### registerApplication method

Source: https://pub.dev/documentation/ngdart/latest/angular/TestabilityRegistry/registerApplication.html

Associates an appRoot with the provided testability instance.

```APIDOC
## registerApplication

### Description
Associates an `appRoot` element with the provided `testability` instance.

### Method Signature
`void registerApplication(Element appRoot, Testability testability)`

### Parameters
#### Path Parameters
- **appRoot** (Element) - The root element of the application.
- **testability** (Testability) - The Testability instance to associate with the appRoot.

### Implementation Details
This method internally calls `initializeEagerly()` and stores the association between `appRoot` and `testability` in a map `_appRoots`.
```

--------------------------------

### Get an instance from the injector

Source: https://pub.dev/documentation/ngdart/latest/di/Injector/get.html

Use this to retrieve a service or dependency from the injector. If the token is not found, it will throw an error by default.

```dart
HeroService heroService = injector.get(HeroService);
```

--------------------------------

### Get hasPendingMicrotasks Property

Source: https://pub.dev/documentation/ngdart/latest/angular/NgZone/hasPendingMicrotasks.html

This property returns a boolean indicating if there are pending microtasks. Most users should not need or use this value.

```dart
bool get hasPendingMicrotasks => _hasPendingMicrotasks;
```

--------------------------------

### NgZone()

Source: https://pub.dev/documentation/ngdart/latest/angular/NgZone-class.html

Constructs a new NgZone instance.

```APIDOC
## NgZone()

### Description
Constructs a new NgZone instance.

### Constructor
NgZone()
```

--------------------------------

### Get the number of attached views

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/length.html

Use the `length` property to retrieve the count of views currently in the container. This property is read-only.

```dart
int get length;
```

--------------------------------

### Initialize JS-Interop Eagerly

Source: https://pub.dev/documentation/ngdart/latest/angular/TestabilityRegistry/initializeEagerly.html

This method eagerly initializes the JS-interop bits. It ensures that the _proxy is created and added to the window if it hasn't been already.

```dart
void initializeEagerly() {
  _proxy ??= _TestabilityProxy()..addToWindow(this);
}
```

--------------------------------

### Get Injector from ViewContainerRef

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/injector.html

Access the Injector associated with the ViewContainerRef. This injector provides the context for dependency injection within the view.

```typescript
Injector get injector;
```

--------------------------------

### Get Index of a ViewRef

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/indexOf.html

Returns the index of the attached `viewRef`. Returns -1 if this container doesn't contain the provided view.

```typescript
int indexOf(ViewRef viewRef);
```

--------------------------------

### Define Injectable Class and Component Using viewProviders

Source: https://pub.dev/documentation/ngdart/latest/di/Component/viewProviders.html

Demonstrates how to define an injectable class (Greeter) and a component (HelloWorld) that uses viewProviders to make Greeter available to its view. The NeedsGreeter directive injects Greeter.

```dart
class Greeter {
   greet(String name) => 'Hello ${name}!';
}

@Directive(
  selector: 'needs-greeter'
)
class NeedsGreeter {
  final Greeter greeter;

  NeedsGreeter(this.greeter);
}

@Component(
  selector: 'greet',
  viewProviders: [
    Greeter
  ],
  template: '<needs-greeter></needs-greeter>',
  directives: [NeedsGreeter]
)
class HelloWorld {
}


```

--------------------------------

### Convert ChangeDetectionStrategy to String

Source: https://pub.dev/documentation/ngdart/latest/angular/ChangeDetectionStrategy/toPrettyString.html

Use this method to get a string representation of the ChangeDetectionStrategy. It handles Default, OnPush, and any other internal strategies.

```typescript
static String toPrettyString(int strategy) {
  switch (strategy) {
    case Default:
      return 'Default';
    case OnPush:
      return 'OnPush';
    default:
      return 'Internal';
  }
}
```

--------------------------------

### Constructors

Source: https://pub.dev/documentation/ngdart/latest/angular/TestabilityRegistry-class.html

Initializes a new instance of the TestabilityRegistry.

```APIDOC
## TestabilityRegistry()

### Description
Initializes a new instance of the TestabilityRegistry.

### Method
Constructor
```

--------------------------------

### HostListener Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/HostListener/HostListener.html

Provides the implementation for the HostListener constructor.

```dart
const HostListener(this.eventName, [this.args]);
```

--------------------------------

### Implicit Host Binding Name

Source: https://pub.dev/documentation/ngdart/latest/angular/HostBinding-class.html

When hostPropertyName is not specified, it defaults to the property or getter name. This example shows how 'title' is implicitly used.

```dart
@Directive(...)
class ImplicitName {
  // Same as @HostBinding('title')
  @HostBinding()
  final title = 'Hello World';
}
```

--------------------------------

### Subclassing OpaqueToken

Source: https://pub.dev/documentation/ngdart/latest/di/OpaqueToken-class.html

Illustrates how to create a more specific token by subclassing OpaqueToken.

```APIDOC
## Subclassing OpaqueToken

### Description
This example demonstrates creating a custom token `LoginUrl` by extending `OpaqueToken`. This allows for more type safety and specificity when defining tokens.

### Code
```dart
class LoginUrl extends OpaqueToken<String> {
  const LoginUrl();
}

const loginUrl = const LoginUrl();

@Component(
  selector: 'dashboard',
  providers: const [
    const ValueProvider.forToken(loginUrl, 'https://someurl.com'),
  ],
)
class DashboardComponent {}
```
```

--------------------------------

### Static Methods

Source: https://pub.dev/documentation/ngdart/latest/di/ReflectiveInjector-class.html

Static methods for creating and initializing ReflectiveInjector instances.

```APIDOC
## Static Methods

resolveAndCreate(List<Object> providersOrLists, [Injector? parent]) → ReflectiveInjector
     Creates a new Injector that resolves `Provider` instances at runtime.

resolveStaticAndCreate(List<Object> providersOrLists, [Injector? parent]) → ReflectiveInjector
     Creates a new Injector that resolves some `Provider` instances.
```

--------------------------------

### ngOnInit Method

Source: https://pub.dev/documentation/ngdart/latest/angular/OnInit-class.html

The ngOnInit method is called once after the first change-detection run for a directive. It's a lifecycle hook that allows you to perform setup tasks.

```APIDOC
## ngOnInit() 

### Description
Executed after the first change detection run for a directive. This method is typically used for initialization logic that depends on the directive's data-bound properties.

### Signature
`void ngOnInit()`

### Example Usage
```dart
@Component(
  selector: 'user-panel',
  directives: const [NgFor],
  template: r'''
    <li *ngFor="let user of users">
      {{user}}
    </li>
  ''',
)
class UserPanel implements OnInit {
  final RpcService _rpcService;
  List<String> users = const [];

  UserPanel(this._rpcService);

  @override
  void ngOnInit() async {
    users = await _rpcService.getUsers();
  }
}
```

### Warning
AngularDart may execute ngOnInit a second time if an exception occurs during change detection as part of its crash detection mechanism.
```

--------------------------------

### Output Constructor

Source: https://pub.dev/documentation/ngdart/latest/di/Output/Output.html

The Output class has a constructor that can optionally take a bindingPropertyName.

```APIDOC
## Output Constructor

### Description
Creates a new instance of the Output class. The constructor accepts an optional `bindingPropertyName`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```dart
const Output([this.bindingPropertyName]);
```

### Parameters
- **bindingPropertyName** (String?) - Optional - The name of the property to bind to.
```

--------------------------------

### FactoryProvider.forToken Implementation

Source: https://pub.dev/documentation/ngdart/latest/di/FactoryProvider/FactoryProvider.forToken.html

Shows the implementation of the FactoryProvider.forToken constructor, which is a factory constructor.

```dart
const factory FactoryProvider.forToken(
  OpaqueToken<T> token,
  Function useFactory,
  {
  List<Object>? deps,
}) = FactoryProvider<T>._;
```

--------------------------------

### run

Source: https://pub.dev/documentation/ngdart/latest/angular/ApplicationRef-class.html

Runs the given callback in the zone and returns the result of that call.

```APIDOC
## run<R>(FutureOr<R> callback())

### Description
Runs the given `callback` in the zone and returns the result of that call.

### Method
run

### Parameters
#### Path Parameters
- **callback** (FutureOr<R> callback()) - Required - The callback function to run.
```

--------------------------------

### Accessing the parent injector in Angular

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/parentInjector.html

Use the parentInjector property to get the injector of the parent component. This is useful for accessing services or dependencies provided by the parent.

```typescript
Injector get parentInjector;
```

--------------------------------

### Provide a Class Directly

Source: https://pub.dev/documentation/ngdart/latest/di/ClassProvider-class.html

Use `ClassProvider` to configure dependency injection to provide an instance of the specified class (`Service`) when its token is requested. This is the most basic usage.

```dart
const ClassProvider(Service);
```

--------------------------------

### Get View by Index - ViewContainerRef

Source: https://pub.dev/documentation/ngdart/latest/angular/ViewContainerRef/get.html

Use this method to retrieve a specific view from the ViewContainerRef using its index. Ensure the index is within the bounds of the container.

```typescript
ViewRef get(int index);
```

--------------------------------

### ExistingProvider Constructors

Source: https://pub.dev/documentation/ngdart/latest/di/ExistingProvider-class.html

Constructors for the ExistingProvider class.

```APIDOC
## Constructors 

ExistingProvider(Type type, Object useExisting)

const
factory 

ExistingProvider.forToken(OpaqueToken<T> token, Object useExisting)

const
factory
```

--------------------------------

### Get NgZone isRunning Status

Source: https://pub.dev/documentation/ngdart/latest/angular/NgZone/isRunning.html

Check the current state of the NgZone. This getter returns true if the zone is actively running tasks and false otherwise.

```dart
bool get isRunning => _isRunning;
```

--------------------------------

### runAppAsync<T extends Object>

Source: https://pub.dev/documentation/ngdart/latest/angular/runAppAsync.html

Asynchronous alternative to runApp, supporting `beforeComponentCreated`. The provided callback (`beforeComponentCreated`) is invoked _before_ creating the root component, with a handle to the root injector. The user must return a `Future` - it will be `await`-ed before creating the root component.

```APIDOC
## runAppAsync<T extends Object>

### Description
Asynchronous alternative to runApp, supporting `beforeComponentCreated`. The provided callback (`beforeComponentCreated`) is invoked _before_ creating the root component, with a handle to the root injector. The user must return a `Future` - it will be `await`-ed before creating the root component.
See runApp for additional details.

### Method Signature
Future<ComponentRef<T>> runAppAsync<T extends Object>(
  ComponentFactory<T> componentFactory,
  {
  required Future<void> Function(Injector) beforeComponentCreated,
  InjectorFactory createInjector = _identityInjector,
}
)
```

--------------------------------

### bootstrapStatic<T extends Object>

Source: https://pub.dev/documentation/ngdart/latest/angular/bootstrapStatic.html

Starts a new AngularDart application with `componentType` as the root. This function is deprecated and has been renamed to `runAppLegacy`. See `runApp` for the preferred API.

```APIDOC
## bootstrapStatic<T extends Object>

### Description
Starts a new AngularDart application with `componentType` as the root. See `runAppLegacy` for the new name of this method.

### @Deprecated
Renamed "runAppLegacy". See "runApp" for the preferred API.

### Signature
Future<ComponentRef<T>> bootstrapStatic<T extends Object>(
  Type componentType,
  [List<Object> providers = const [],
  void Function()? initReflector]
)

### Parameters
* `componentType` (Type) - The root component type for the application.
* `providers` (List<Object>) - Optional list of providers to configure the application's injector.
* `initReflector` (void Function()?) - Optional function to initialize the reflector.

### Returns
* Future<ComponentRef<T>> - A future that completes with a reference to the root component.
```

--------------------------------

### run<R> method

Source: https://pub.dev/documentation/ngdart/latest/angular/ApplicationRef/run.html

Runs the given `callback` in the zone and returns the result of that call. Exceptions will be forwarded to the exception handler and rethrown.

```APIDOC
## run<R> method

### Description
Runs the given `callback` in the zone and returns the result of that call. Exceptions will be forwarded to the exception handler and rethrown.

### Method Signature
`FutureOr<R> run<R>(FutureOr<R> callback())`

### Parameters
#### callback
- **callback** (Function): A function that returns a `FutureOr<R>`.

### Returns
- `FutureOr<R>`: The result of the callback function.
```

--------------------------------

### Querying Projected Content with NgContentRef

Source: https://pub.dev/documentation/ngdart/latest/angular/NgContentRef-class.html

This example demonstrates how to use NgContentRef to check if an `<ng-content>` element has any projected nodes. If no content is projected, default content is displayed.

```dart
@Component(
  selector: 'comp',
  template: '''
    <ng-content #projectedContent></ng-content>
    <div *ngIf="!projectedContent.hasContent">
      There was no projected content. Here is some default content!
    </div>
  ''',
)
class FooComponent {
  @ViewChild(NgContentRef)
  NgContentRef child;
}

```

--------------------------------

### EmbeddedViewRef Example Rendering

Source: https://pub.dev/documentation/ngdart/latest/angular/EmbeddedViewRef-class.html

Shows the rendered output of a template using `ngFor`, where each item in the `items` array results in an `EmbeddedViewRef` being created and rendered as an `<li>` element.

```html
<ul>
  <!-- EmbeddedViewRef -->
  <li>First</li>
  <!-- EmbeddedViewRef -->
  <li>Second</li>
</ul>

```

--------------------------------

### runAppLegacyAsync Function Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/runAppLegacyAsync.html

This is the legacy implementation of runAppAsync. It initializes the reflector if provided and then calls runAppAsync with a factory for the component type and a custom injector created from the provided providers.

```dart
Future<ComponentRef<T>> runAppLegacyAsync<T extends Object>(
  Type componentType, {
  required Future<void> Function(Injector) beforeComponentCreated,
  List<Object> createInjectorFromProviders = const [],
  void Function()? initReflector,
}) {
  assert(T == Object || T == componentType, 'Expected $componentType == $T');
  if (initReflector != null) {
    initReflector();
  }
  return runAppAsync(
    unsafeCast(typeToFactory(componentType)),
    beforeComponentCreated: beforeComponentCreated,
    createInjector: (parent) {
      return ReflectiveInjector.resolveAndCreate(
        [
          createInjectorFromProviders,
        ],
        unsafeCast(parent),
      );
    },
  );
}
```

--------------------------------

### Angular ngOnDestroy Implementation

Source: https://pub.dev/documentation/ngdart/latest/angular/AsyncPipe/ngOnDestroy.html

Implement the ngOnDestroy method to perform cleanup tasks when a directive is destroyed. This example checks if a subscription exists before calling a dispose method.

```typescript
@override
void ngOnDestroy() {
  if (_subscription != null) {
    _dispose();
  }
}
```

--------------------------------

### ValueProvider Constructor

Source: https://pub.dev/documentation/ngdart/latest/di/ValueProvider/ValueProvider.html

Constructs a new ValueProvider instance.

```APIDOC
## ValueProvider<T extends Object> constructor

### Description
Creates a new instance of ValueProvider.

### Parameters
- **type** (Type) - Required - The type of the value.
- **useValue** (T) - Required - The value to be provided.
```

--------------------------------

### Get Testability Instance

Source: https://pub.dev/documentation/ngdart/latest/angular/TestabilityRegistry/testabilityFor.html

Use this method to retrieve the testability instance for a given application root element. Returns null if no testability instance is registered for the element.

```dart
Testability? testabilityFor(Element appRoot) => _appRoots[appRoot];
```

--------------------------------

### ValueProvider.forToken Constructor

Source: https://pub.dev/documentation/ngdart/latest/di/ValueProvider/ValueProvider.forToken.html

The `ValueProvider.forToken` constructor takes an `OpaqueToken` and a `useValue` to create a provider.

```APIDOC
## ValueProvider.forToken Constructor

### Description
Creates a `ValueProvider` that provides a specific value associated with an `OpaqueToken`.

### Signature
```dart
const factory ValueProvider.forToken<T extends Object>(
  OpaqueToken<T> token,
  T useValue,
)
```

### Parameters
#### Path Parameters
- **token** (OpaqueToken<T>) - Required - The opaque token to associate with the provided value.
- **useValue** (T) - Required - The value to be provided by this `ValueProvider`.

### Implementation
```dart
const factory ValueProvider.forToken(
  OpaqueToken<T> token,
  T useValue,
) = ValueProvider<T>._;
```
```

--------------------------------

### runApp with Custom Injector

Source: https://pub.dev/documentation/ngdart/latest/angular/runApp.html

Starts an AngularDart application with a custom injector to provide services. The `createInjector` function is used to define the application's service providers.

```dart
import 'package:ngdart/angular.dart';
import 'main.template.dart' as ng;

@Component(
  selector: 'hello-world',
  template: '',
)
class HelloWorld {
  HelloWorld(HelloService service) {
    service.sayHello();
  }
}

class HelloService {
  void sayHello() {
    print('Hello World!');
  }
}

void main() {
  runApp(ng.HelloWorldNgFactory, createInjector: helloInjector);
}

@GenerateInjector(const const ClassProvider(HelloService))
final InjectorFactory helloInjector = ng.helloInjector$Injector;
```

--------------------------------

### ExistingProvider Methods

Source: https://pub.dev/documentation/ngdart/latest/di/ExistingProvider-class.html

Methods available on the ExistingProvider class.

```APIDOC
## Methods 

noSuchMethod(Invocation invocation) → dynamic
     Invoked when a nonexistent method or property is accessed. 
inherited 

toString() → String
     A string representation of this object. 
inherited
```

--------------------------------

### ExistingProvider.forToken Constructor

Source: https://pub.dev/documentation/ngdart/latest/di/ExistingProvider/ExistingProvider.forToken.html

The `ExistingProvider.forToken` constructor takes an `OpaqueToken` and an `Object` representing the existing value to be provided.

```APIDOC
## ExistingProvider.forToken Constructor

### Description
Creates an `ExistingProvider` that provides an existing value associated with a given token.

### Parameters
- **token** (OpaqueToken<T>) - The token identifying the existing value.
- **useExisting** (Object) - The existing value to be provided.
```

--------------------------------

### SlicePipe transform method

Source: https://pub.dev/documentation/ngdart/latest/angular/SlicePipe-class.html

The `transform` method is the core of the SlicePipe, taking a value (List or String) and optional start and end indices to return a sliced portion.

```APIDOC
## transform(dynamic value, int start, [int? end]) 

### Description
Creates a new List or String containing a subset (slice) of the elements from the input `value`.

### Parameters
#### Path Parameters
- **value** (dynamic) - Required - The input List or String to slice.
- **start** (int) - Required - The starting index of the subset. Can be positive or negative.
- **end** (int?) - Optional - The ending index of the subset. Can be positive or negative. If omitted, slices to the end.
```
Tokens:
Raw