DEV Community: Gianpiero Errigo

Angular 15: what happened to environment.ts

Gianpiero Errigo — Fri, 27 Jan 2023 19:21:20 +0000

TL;DR: Nothing!

Angular 15 simply doesn't ship anymore environment files by default.
You can still create them and configure their replacement based on build target as it was done automatically at project creation in previous versions.

A misunderstood purpose

The origin of the confusion, arising lately about the missing of these files in new project created with ng-cli at version 15, has its roots in the misconception that src/environments/environment.ts and src/environments/environment.prod.ts were some kind of sacred paths hardcoded in the deepest guts of Angular framework.
Reality is that they were just a convenience default choice, with no reference in codebase, and that could have been substituted by different paths and names with no harm to the application.

Original role

The only place in code where you could find them referenced at project creation was main.ts, generated with something like this:

...
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}
...

Their environment.production property was used to check if the build just booted had to enable ProdMode or not.
This function was turning off a flag (yes, the flag is indeed isDevMode, and not isProdMode like one could expect) actually checked in Angular codebase to toggle some "debugging" features, most evident of which is the familiar message logged in console

Angular is running in development mode.
Call enableProdMode() to enable production mode.

When the flag is true, it means we are running a development stage of our app, so we want the framework to be more verbose in warnings and errors, and even to be a bit more "pedantic" checking situations that are not an error per-se, but that could lead to undesired and often erroneous behaviour in production.
Famous one is surely NG0100: Expression has changed after it was checked, responsible of verifying our data-binding follows a unidirectional flow, something that could bring problems during execution, but that will not throw errors on its own at runtime.

Originally Angular had no way to switch this flag other than putting the function in a file parsed at bootstrap.

Black magic of file replacement

People tended to accept the interpretation of the
correct file to load as faith, without questioning how the framework was capable of reading environment.ts or environment.prod.ts accordingly to the build target of choice.
The answer was nothing involving deep understanding of Angular inner mechanisms, but just the use of a nice feature offered by its builder, that while parsing configuration for chosen target, was instructed to take in account fileReplacements array, issuing the substitution defined in its objects.
This was default config for production build some versions ago:

"configurations": {
...
  "production": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.prod.ts"
      }
    ],
...

Nothing was preventing us to add new replacements or change default one but, if the latter, we should have considered to modify our main.ts to check in the right file for the environment.production property it used to toggle production flag.

What changed in version 15

Last major release of Angular leverages a different system to toggle production flag: it lets optimization builder option, by default passed to production build target, set global NgDevMode to false, without having to parse any env file.

This change took off the only reason to have any environment file in the beginning, leading devs to get rid of them completely and obviously removing default fileReplacements occurrences in build targets configuration.

Why people are freaking out

Looking at what we read so far, it looks like this new approach is not something that should affect majority of Angular applications developers, being it more an "internal" of the framework.
Thing is that, being these files already generated at project creation and correctly managed on a build target basis, it became common practice using them to store a bunch of values that need to be switched between production and development build.
Usually these involved address of API servers to contact and Auth providers configurations.

Without finding the files where expected on newly generated projects, people who never had been interested in understanding how they ever worked didn't know where to put these data, unaware of the simplicity of manually reproducing the original setup.

Lazy solution

After the huge amount of complaints about this, Angular devs choose to "restore" on demand something similar to the old behaviour in 15.1 release.

So, from that version onwards, having environment files in place after creating a project is as simple as issuing

ng generate environments

that as explained in docs will create them and configure build and server targets to use them.

In short: it will create src/environments/environment.ts and src/environments/environment.development.ts adding the latter as replacement of the former for build configuration's development target

"development": {
...
  "fileReplacements": [
    {
      "replace": "src/environments/environment.ts",
      "with": "src/environments/environment.development.ts"
    }
  ]

Why they didn't think of that before

The habit of putting environment variables inside those files is less straightforward than it could seem.
Even if their name and their use could lead to look at them as the ideal spot for such information, in real case scenario they're far from best solution.
Data like domains, endpoints, ports and alike are not bound only to building target, but often more tightly to deployment context.
That's why many people prefer to keep them outside of building process, and let the app evaluating them at runtime as token injected at deploying, maybe as environment variable of the hosting framework or docker bundling, read by a minimal server side process and exposed as API, or even passing them in dedicated configuration file inserted as assets by pipeline, as explained in this awesome article from good ol' @frederikprijck.

Now it should be clear there's been no change in environment variables management by Angular, just an upgrade that made an old easy convenient configuration not needed anymore, leading to reconsider what had always been an habit that often was a suboptimal solution, but that's available as it always has been.

Cheers.

Nx Module Federation bad Angular routing

Gianpiero Errigo — Sun, 22 Jan 2023 12:37:33 +0000

While puzzling around with Nx' Webpack Module Federation support, I stumbled upon an issue that strangely looks like none cared about before.
I'm talking about duplication of remote component in presence of a <router-outlet> in its template, when served as independent app.
Its poor traction could be due to the fact the bug shows up only using an Angular Standalone Components setup, at least for remotes.

The issue

I will take for granted the creation of a Module Federated Angular app under Nx.
After scaffolding, we should have an host app acting as shell of our multi-module project, and at least one remote app.
Both of them are Micro-Frontends, meaning they are capable of running on their own, even the remote one.
That comes clear issuing nx serve host_project_name, where they will be served independently, giving you the chance to look at their behaviour both when remote is accessed as child route of the host, both when it's booted as standalone app.

To make thing barely functional, our host app consists of a single dumb component with two lines template:

@Component({
  selector: 'testapp-root',
  template: `
             <a routerLink="remote_app">Remote</a>
             <router-outlet></router-outlet>
            `,
})
export class RemoteEntryComponent {}

Just an anchor linking to the remote, and a router-outlet under which the child will be rendered.

Similarly, the remote will be just a visual aid to show our issue

@Component({
  selector: 'testapp-remote1-entry',
  template: `
              <div style="background-color: blue; height: 100px; width: 100px; margin: 5px"></div>
            `
})
export class RemoteEntryComponent {}

Here we got merely a square div coloured in blue.

That's it.
Let's look at what gets served, then.
For our host app we'll get just the link, that once clicked will route to the remote, that will appear right under it (and under host's <router-outlet>)

If we browse to the standalone remote served app, by default reachable at host_port+1, thus on http://localhost:4201 for a classic setup, we'll see our remote content, the blue square, immediately rendered and no host's anchor element, as expected.

So, where's the problem?
The issue we're talking about arises if we add a <router-outlet> element to our remote.
This is quite a common situation: many times our microfrontend will have its own internal routing, with child paths and obviously a router-outlet under which rendering them.
This is our modified remote

@Component({
  selector: 'testapp-remote1-entry',
  template: `
              <div style="background-color: blue; height: 100px; width: 100px; margin: 5px"></div>
              <router-outlet>
            `
})
export class RemoteEntryComponent {}

In this short GIF we can see how it still works flawlessy when rendered as child of our host app, while acting really strangely when browsing to its standalone serving:

Our remote is rendered twice!

The reason

To understand the reason behind this wrong behaviour, we got to dive a little deep into tech used by Nx plugins to manage Webpack Module Federation for Angular apps.
For the host app there's nothing too fancy: it gets served as standalone, and if needed is able to load external modules through a little twist of normal routing:

{
  path: 'remote_app',
  loadChildren: () =>
    loadRemoteModule('rem1', './Routes').then((m) => m.remoteRoutes),
}

See how as callback of Angular Router's loadChildren, instead of classic import(path/to/lazy_loaded.module) we got a call to Nx provided loadRemoteModule('remote_module_name', './exposed_routes_path').

Inside our remote's module-federation.config.js there's the mapping for arguments passed to that call:

module.exports = {
  name: 'rem1',
  exposes: {
    './Routes': 'apps/rem1/src/app/remote-entry/entry.routes.ts',
  },
};

So: the host's Router will look inside remote's entry.route.ts to know which child routes it could render.
This is default generated entry.route.ts

export const remoteRoutes: Route[] = [
  { path: '', component: RemoteEntryComponent },
];

As we could imagine, there's just a root path '' pointing to default remote's root component, commonly referred as entry component.
This is nice for a situation where our remote is treated as accessory module of a main app.
All its structure is just a lazy-loaded branch inside host routing tree.

Things drastically change when our remote has to be served as an independent app.
Without a "parent" app already up and running, it needs to be bootstrapped as any other Angular application.
The flow Nx relies on starts with the usual serving of an index.html built upon a template like this:

<!DOCTYPE html>
<html lang="en">
  <head>...</head>
  <body>
    <testapp-remote1-entry></testapp-remote1-entry>
  </body>
</html>

In place of Angular-cli generated <app-root></app-root> selector assigned to AppComponent, body has been populated with our custom remote entry component's selector.
The code then sources main.ts as always, that delegates to bootstrap.ts file.
Here takes place the actual application bootstrapping, that for an Angular Standalone Components setup (concept unrelated to standalone serving of our remote, don't get confused) could be enough something like:

bootstrapApplication(RemoteEntryComponent)

Nx remotes generator takes one step further providing to our Router eventual inner routes defined for this remote:

...
import { appRoutes } from './app/app.routes';

bootstrapApplication(RemoteEntryComponent, {
  providers: [
    importProvidersFrom(
      RouterModule.forRoot(appRoutes, { initialNavigation: 'enabledBlocking' })
    ),
  ],
});

This ./app/app.routes simply lazy loads the same entry.routes file exposed to our host app.

export const appRoutes: Route[] = [
  {
    path: '',
    loadChildren: () =>
      import('./remote-entry/entry.routes').then((m) => m.remoteRoutes),
  },
];

And here comes the problem!
We've already seen that file provides a route to root path '' rendering the root component of our remote.
But in our remote independent serving that component is already rendered due to its reference inside remote's index.html template.
This graph should be explanatory enough:

As the purple highlighted labels emphasize, the path to rendering of the entry component for independent remote serving encounters two different locations asking for it.
That entry component is actually both declared both routed.

Why the issue doesn't occur with old NgModule-based remotes setup instead of standalone components?

Because Nx remotes generator for classic ng-modular setup doesn't need to declare the entry component inside index.html.
It declares a separate root component (AppComponent) hosting a <router-outlet> and imports RouterModule inside root module (AppModule).
This way the same route referring to entry component will be correctly rendered just once both for Shell setup than for independent remote serving.

My solution

The problem can be probably solved in many ways, since every sane solution involves a partial rewriting of Nx generators for remotes built upon Angular standalone components.

Mi idea is to distinguish the purpose of remote's app.routes and entry.routes.
At the moment the former simply lazyloads the second, leading to an identical initial routing flow for both serving contexts.
Instead I thought of turning app.routes into the real route provider for remote, and leaving entry.routes just as a "plugin" invoked only in Shell serving context, keeping needed root path pointing to entry component, and importing app.routes to use defined routes as its children.

To do this, first we modify app.routes, removing its entry.routes lazy load, and adding our remote children routes to its array.
To keep entry.routes inside our compilation unit we move its import outside of routes definition, so it will be still compiled and exposed by our federation configuration, but ignored by our router during independent serving:

/* commented-out original default entry.routes import 
export const appRoutes: Route[] = [
  {
    path: '',
    loadChildren: () =>
      import('./remote-entry/entry.routes').then((m) => m.remoteRoutes),
  },
]; */

import('./remote-entry/entry.routes')

export const appRoutes: Route[] = [
  { path: 'first_child_route', component: FirstChildRouteComponent },
  { path: 'second_child_route', component: SecondChildRouteComponent },
  { path: 'third_child_route', component: ThirdChildRouteComponent }, 
]

Now we can edit entry.routes, enriching its only route with an array of children, simply importing the one defined in app.routes

import { appRoutes } from '../app.routes';
import { RemoteEntryComponent } from './entry.component';

export const remoteRoutes: Route[] = [
  { 
    path: '',
    component: RemoteEntryComponent,
    children: appRoutes
  }
];

In the end we can appreciate the result of our efforts, looking at our blue square rendered a single time for any serving methodology:

Conclusions

I think Nx support for Angular standalone components federation is still a bit "unripe".
I found a couple oddities in its implementation I'll spend some words about in a future article, maybe.
It does a great job though, raising the coder from writing a lot of boilerplate and, considering I'm not exactly an expert in this field, there's the chance some of the things looking like "flaws" to me, were real solutions for cornercases or common use scenarios I didn't think of.
For the very same reason, the one I presented as a "solution" could be sub-optimal if not even wrong for other situations.
I didn't test it extensively, that's why as usual you're highly encouraged to leave a comment if anything doesn't sound right.

Anyway, I opened a ticket for this specific bug, and issued a PR with my suggested solution:

Duplicate entry component rendering for standalone ng component served as independent frontend #14551

4javier posted on Jan 23, 2023

Current Behavior

When generating angular standalone component as remote, the entry component is listed inside entry.routes for root path ''. That's fine when module is lazy loaded by shell app, but gives a problem when served as independent microfrontend. In that case the entry component is declared into index.html too, so if a router-outlet gets added somewhere in the tree, the component will be rendered twice.

Expected Behavior

When served as independent app, entry.routes should be ignored, and inner routes should be defined into remote's app.routes directly.

Github Repo

https://github.com/4javier/monotest

Steps to Reproduce

nx serve shell
on localhost:4200 click on "remote" link: a blue square is rendered
on localhost:4201: two squares get rendered

Nx Report

Node : 14.20.0
   OS   : linux x64
   npm  : 6.14.17
   
   nx : 15.5.1
   @nrwl/angular : 15.5.1
   @nrwl/cypress : 15.5.1
   @nrwl/detox : Not Found
   @nrwl/devkit : 15.5.1
   @nrwl/esbuild : Not Found
   @nrwl/eslint-plugin-nx : 15.5.1
   @nrwl/expo : Not Found
   @nrwl/express : Not Found
   @nrwl/jest : 15.5.1
   @nrwl/js : 15.5.1
   @nrwl/linter : 15.5.1
   @nrwl/nest : Not Found
   @nrwl/next : Not Found
   @nrwl/node : Not Found
   @nrwl/nx-cloud : Not Found
   @nrwl/nx-plugin : Not Found
   @nrwl/react : Not Found
   @nrwl/react-native : Not Found
   @nrwl/rollup : Not Found
   @nrwl/schematics : Not Found
   @nrwl/storybook : Not Found
   @nrwl/web : Not Found
   @nrwl/webpack : 15.5.1
   @nrwl/workspace : 15.5.1
   @nrwl/vite : Not Found
   typescript : 4.8.4
   ---------------------------------------
   Local workspace plugins:
   ---------------------------------------
   Community plugins:

Failure Logs

No response

Additional Information

I explained extensively the issue and my suggested solution here. https://dev.to/this-is-angular/nx-module-federation-bad-angular-routing-1ac9

View on GitHub

Cheers.

Material forms: mat-checkbox disabling controls

Gianpiero Errigo — Thu, 12 Jan 2023 10:55:51 +0000

In previous article we analyzed a generic workflow for the creation of a directive capable of adding a native checkbox element to a basic form in pure good-old HTML.
Now we'll try to replicate the idea on a more realistic usecase involving some common Angular Material Components often used in forms composition.
Here pitfalls and tradeoffs will be more evident and will probably make you questioning once more if a global directive of this kind is a convenient solution.

Recap our goals

After reading first article of the series, it should be clear which features our checkbox should provide:

reflect initial enabling status of bound control at start
switch that status on click
listen to any control status changing issued programmatically and modify its own state accordingly

This time we will setup a more realistic harness, a common structure for a really simple form:

a flex-direction: column flexbox container to vertically host our controls one-per-line
material elements wrapping our native controls
- we will notice how Material makes extensive use of content projection, often flooding DOM tree beyond any expectation
- we will consider to leverage some nice properties these wrapping components expose
to be consistent with Material Design, our plain HTML <input type="checkbox"> will be replaced by its glorified Material version mat-checkbox

Our Angular Material reference version will be the new one (15.x) based on Material Design Components for Web (MDC).
Its API shouldn't be too different than previous versions, though.

This second version of our directive will get the selector: selectableMat, while we'll recycle the old model:

plainForm = new FormGroup({
    text: new FormControl(''),
    number: new FormControl(0),
    radio: new FormControl('no'),
    range: new FormControl(0),
    singleSel: new FormControl(''),
    multiSel: new FormControl([]),
  });

and here its template:

<div class="container" [formGroup]="plainForm">
    <mat-form-field selectableMat>
        <mat-label>A text control</mat-label>
        <input matInput formControlName="text" >
    </mat-form-field>
    <mat-form-field selectableMat>
        <mat-label>A number control</mat-label>
        <input matInput formControlName="number" type="number" >
    </mat-form-field>
    <label>A radio control</label>
    <mat-radio-group formControlName="radio" selectableMat>
        <mat-radio-button value="yes">Yes</mat-radio-button>
        <mat-radio-button value="no">No</mat-radio-button>
    </mat-radio-group>
    <label>A range control</label><br>
    <mat-slider selectableMat>
        <input formControlName="range" matSliderThumb >
    </mat-slider>
    <mat-form-field selectableMat>
        <mat-label>A single selection control</mat-label>
        <mat-select formControlName="singleSel" >
            <mat-option value="">--Please choose an option--</mat-option>
            <mat-option value="dog">Dog</mat-option>
            <mat-option value="cat">Cat</mat-option>
            <mat-option value="hamster">Hamster</mat-option>
        </mat-select>
    </mat-form-field>
    <mat-form-field selectableMat>
        <mat-label>A multiple selection control</mat-label>
        <mat-select formControlName="multiSel" multiple >
            <mat-option value="">--Please choose multiple options--</mat-option>
            <mat-option value="dog">Dog</mat-option>
            <mat-option value="cat">Cat</mat-option>
            <mat-option value="hamster">Hamster</mat-option>
        </mat-select>
    </mat-form-field>
    <button (click)="showSubmitObject()">Submit</button>
</div>

Don't worry, we're gonna examine every control one by one.

Replacing plain checkbox with fancy `mat-checkbox`: nice, but...

We already said that, being in a Material environment, we want to replace our plain old browser-styled checkbox with a posh MatCheckbox component.
Sounds good, but there's a problem: mat-checkbox is not a registered element, thus our Renderer2 cannot call WEBApi's Document interface to create it.
We got to dynamically generate it as a component in the Angular way.
This means that our directive will have to get a reference of its host element's ViewContainer, and append inside it the newly generated checkbox View.
It's way easier than it sounds, and we can see it in action in the early lines of our directive:

disablingCheckbox: ComponentRef<MatCheckbox>;
constructor(
    private vcr: ViewContainerRef,
    ...
) {
  this.disablingCheckbox = this.vcr.createComponent(MatCheckbox) 
  ...

We declare a property typed as a ComponentRef generated by a factory of MatCheckbox components to have access to its properties later, inject in constructor the ViewContainerRef of the element to which the directive has been applied, and then create an instance of the component through ViewContainerRef.createComponent, without passing any index argument, so that the method will append it as ViewContainer's last child.

Here we got to stop a second and do some considerations: since we need to access the host's ViewContainerRef, we got to carefully ponder over the element on which applying our directive selector, because it will condition not only the tokens we can access without querying, but the View after which the MatCheckbox will be rendered, too.
Let's try to explain with an example, involving a mat-form-field:
If we were applying our directive to the inner <input>

<mat-form-field>
    <mat-label>A text control</mat-label>
    <input matInput formControlName="text" selectableMat>
</mat-form-field>

we would have been able to inject NgControl directly in constructor, but our <mat-checkbox> would have been rendered as last child of <mat-form-field>, inheriting its styling and state.
<mat-form-field> wrap its children inside a flex-direction: column flexbox container, so our checkbox will be placed below its last child.
Imagine if we had chosen an horizontal layout, using flex-direction: row for our main container: we would have expected to get our checkbox rendered beside the form field

instead, being it child of the view that's inside <mat-form-field>, it's actually part of the element and positioned below every other children of it

And that's not even the worst problem: as a children of the very same element it's in charge to disable, when unchecked it will inherit the disabled state from its parent, starting a chain with unpredictable consequences (the better, letting the binding form-field & checkbox in an inconsistent state).

That's why we prefer to apply our directive directly on the wrapper element,

<mat-form-field selectableMat>
    <mat-label>A text control</mat-label>
    <input matInput formControlName="text">
</mat-form-field>

this way our checkbox will be placed inside that element's ViewContainer, and not inside element itself, following the layout we defined for its container, and not receiving any state or event from the control it's commanding.
For our vertical layout this will be the result:

Our requirement could easily be a vertical layout but with the checkbox placed beside related control.
Unfortunately there's not a clean way to instruct a directive to do that, and the best solution would be forcing the user to put every single material control wrapper element inside a parent one, on which applying our directive to style that per our needs.
This would defeat the basic idea of a general purpose directive acting on DOM structure: at that point I'm more in favor of one limiting its functionalities to the model, to be applied to a checkbox placed and styled by the user manually in template

How it should be: `<mat-form-field>`

For most common elements available in a form, selects and text-like inputs, both native both in Material variants, Angular Material allows the use of the wrapper mat-form-field.
We will not spend time explaining all the structural and styling modifications it applies to wrapped control, but will focus on some property it exposes, and that apparently could be of interest for the functionalities of our directive.
Anyway, to understand the complexity of the DOM manipulation Material applies, look at how this basic template

<mat-form-field>
    <mat-label>A text control</mat-label>
    <input matInput formControlName="text">

flourishes in this branch after rendering

Back to the API it exposes, most important class is MatFormFieldControl, provided by all supported control elements: for native <input> and <textarea> through the application of matInput directive, and automatically by <mat-select> and <mat-chip-list>.
Among its properties one in particular catches our interest: disabled.
It could serve our project, if only looking at its code we wouldn't realize that

it's a readonly property: thus it's supposed to be accessed just to check status of the control, and not as a setter
it's a plain boolean, not a reactive property like an Observable<boolean>, so it cannot be listen to on its own to get live status of the control

One looking more promising is

ngControl: NgControl | AbstractControlDirective | null

We're familiar with NgControl, we used it in our plain HTML example, and it offers all we need.
Its union type is due to MatFormFieldControl being assignable to controls that can be nullable, and to FormGroup and FormaArray too, that extend AbstractControlDirective through their common ancestor ControlContainer, but not its subclass NgControl.
That's actually not a big problem, considering properties interesting for our usecase are part of the parent class.
Anyway, typings could be a little annoying, considering that MatFormFieldControl is obviously generic, so we should specify its type at injection time other than managing union type of returned value.
So: save ourself a bit of type-narrowing confusion, and access our NgControl the old way, simply querying for it in our projected content:

@ContentChild(NgControl) ctrl!: NgControl;

Nothing different than what MatFormField does in its code, so even the lifecycle access constraint will be identical.

Having retrieved it as @ContentChild we got to put our logic inside ngAfterContentInit(), where it will result defined

ngAfterContentInit() {

  this.disablingCheckbox.instance.change.subscribe(
    v => v.checked ? this.ctrl.control?.enable() : this.ctrl.control?.disable()
  );
...

We leverage @Output() change: EventEmitter<E> from MatCheckbox class to react to user interactions with our checkbox and, through the control property of the NgControl we queried, set the status of FormControl accordingly.

Now, the other way of the binding:

this.ctrl.control?.statusChanges?.pipe(
  startWith(this.ctrl.control?.disabled ? 'DISABLED' : ''),
  tap((status: string) => status === 'DISABLED' 
        ? this.disablingCheckbox.setInput('checked', false)
        : this.disablingCheckbox.setInput('checked', true)
  )
).subscribe()

Remembering from last articles that NgControl.statusChanges does not emit for control initial status, we pipe our observation to the usual startWith emitting a string relatable to the real initial status of the control.
After that, for every emission we'll call ComponentRef.setInput, introduced in Angular 14.1, on our MatCheckbox instance, that will take care of managing change detection cycles for us, while keeping checkbox state consonant with control status.

Outside `<mat-form-field>` things start to branch

<mat-form-field> is designed to host a limited amount of controls element types as we already explained, so for type="radio" and type="range" in our example we need to setup something different.

MatRadioGroup looks like Material component appointed to manage radio type selectors.

<mat-radio-group formControlName="radio" selectableMat>
    <mat-radio-button value="yes">Yes</mat-radio-button>
    <mat-radio-button value="no">No</mat-radio-button>
</mat-radio-group>

First difference we notice is that in this case formControlName is applied to the top-most element together with our directive.
MatRadioGroup class is the one providing NG_VALUE_ACCESSOR, and that actually makes its use a bit more sound than pure HTML example, where the same formControlName binding was applied to every <input type="radio">
This leads to the need of some changes in our approach, because with this configuration NgControl cannot be queried as content, being it directly provided by the host we're targeting.

We could pass an optional NgControl typed argument in constructor, or as I prefer for readability:

@ContentChild(NgControl) 
ctrl!: NgControl;
_radioCtrl?: NgControl;
constructor(
    private vcr: ViewContainerRef,
    private el: ElementRef,
) {

  if (this.el.nativeElement.nodeName === 'MAT-RADIO-GROUP') {
    this._radioCtrl = inject(NgControl);
  }
  ...

We defined a new optional property _radioCtrl typed as NgControl, and inside constructor body we use inject() function introduced in Angular 14, to assign hosting View's NgControl instance to it, only after having checked nodeName property of hosting element retrieved by ElementRef will match the one for MatRadioGroup.

ngAfterContentInit() {

  if (this.el.nativeElement.nodeName === 'MAT-RADIO-GROUP') {
    this.ctrl = this._radioCtrl!;
  }
  ...

Since we wanna keep a common logic no matter which type of control is exposing its NgControl, we got to be sure to assign our freshly created _radioCtrl to generic ctrl property.
But we cannot do this directly in constructor, otherwise it would be overwrote by @ContentChild initialization, resulting in undefined for MatRadioGroup components (remember: for this type of control, formControlName directive is applied to hosting component directly, not to its projected <mat-radio-button>s).
So we put this logic in ngAfterContentInit(), and
like we've done for its injection, we do this only after having checked hosting element nodeName.

The sore point: `<mat-slider>`

Last typology of input left to manage is our type="range".
In general, this type of control doesn't get too much cheers when it shows up in a form.
Styling is far from trivial, even for enterprise-level framework like Bootstrap or Material.
But I got to say: Angular Material reaches a whole new level of entanglement with its mat-slider!

Maybe for the strange nature of range control itself, or for the choice to enrich its functionality adding an optional second thumb to let the user select an interval of values... its implementation is really something.
Theoretically it should be quite a smooth operation:

<mat-slider selectableMat>
    <input formControlName="range" matSliderThumb>
</mat-slider>

We apply our directive to wrapping element, planning to access NgControl through @ContentChild like we did for MatFormField.
But we didn't reckon with matSliderThumb!
This directive has to be applied to the inner <input> element (that internally gets assigned type="range"), because it registers as ControlValueAccessor, giving form capabilities to its parent MatSlider.

Yet its behaviour seems to interfere with normal change detection recognition of the input it's bound to.
For what we've seen, our directive current implementation should deal flawlessy with this new control, because it has a structure comparable with the one of MatFormField, but if we try to assign an initial disabled status to our range control

...
range: new FormControl({value: 0, disabled:true}),
...

or to add a button triggering a programmatically call to its FormControl.disable() method

<button (click)="disableRange()">Disable</button>

disableRange() {
  this.plainForm.controls.range.disable();
}

we'll notice that our dedicated checkbox' state doesn't follow control status change.

Look at the inconsistency between disabled control but flagged checkbox.

In its setter role it works correctly: a first click will uncheck the box without toggling control status, and following ones will act as they're supposed to do.
This means that the problem resides in its listening role

this.ctrl.control?.statusChanges?.pipe(
  startWith(this.ctrl.control?.disabled ? 'DISABLED' : ''),
  tap((status: string) => status === 'DISABLED' 
        ? this.disablingCheckbox.setInput('checked', false)
        : this.disablingCheckbox.setInput('checked', true)
  )
).subscribe()

Debugging at runtime we can see that, unlike what happens with MatFormField, even inside ngAfterContentInit() the property ctrl.control, that reflects the runtime status of underlying AbstractControl for NgControl, is still not initialized as one would expect, returning undefined and missing the subscription on statusChanges event emitter.

The evidence we're facing a timing issue is presented by this ugly hack, where just for testing we register our subscription inside MacroTask by setTimeout

setTimeout(() => this.ctrl.control?.statusChanges?.pipe(
  startWith(this.ctrl.control?.disabled ? 'DISABLED' : ''),
  tap((status: string) => status === 'DISABLED' 
        ? this.disablingCheckbox.setInput('checked', false)
        : this.disablingCheckbox.setInput('checked', true)
  )
).subscribe())

As we can see, control's disabled status, be it set as initial value or asynchronously, is reflected by checkbox state

At the moment I didn't find any elegant solution to overcome the issue, so whoever should know better is welcome in comments as usual. 😃

Conclusions

The goal of this short series is to make people aware of difficulties they can encounter while trying to "generalize" a task that looked repetitive at the limit of copy/pasting.
I think it's now clear that the more advanced the underlying framework for styling and model/view binding, the more challenging the task become.
My suggestion is to always "abstract" something when this actually represents itself a fair amount of times, and not when we think it's something that will come again often.
Maybe there will be another short episode of this series due to my interest in Bootstrap, but in any case, thanks for reading 'til down here.

Angular forms: checkbox disabling controls

Gianpiero Errigo — Mon, 09 Jan 2023 10:24:47 +0000

How to write a directive to add it.

And why you shouldn't.

If as a coder you never found yourself having wasted an unjustifiable amount of time trying to automatize a procedure, just to realize that rewriting it for the couple of times it was actually needed took 1/1000 of resources...
YOU'RE A LIAR!!!

Be honest: everyone, at least at the beginnings, fell for that trap called premature optimization, the root of all evil perfectly summarized in this over-used xkcd strip:

(I know, this is just a "nuance" of many kinds of premature optimization issue, but that's the one we're gonna talk about).

What we'll be showing in this article is an example of those situations: a mildly frequent necessity involving fairly amount of modifications to DOM tree. Something that in real usecase scenarios styled with tools already complex enough on their own, will leave you with the feeling that huge pile of trade-offs and workarounds is not worth the effort.
So, we'll use the pretense of implementing a directive adding a checkbox element to any of our form controls letting users capable of disabling them, to explore some Angular tools aiming at manipulating the project a bit over basic framework use.

Useless harness

In this first article we'll use as example a pure HTML form, with plain controls without any styling, separated by native <hr> tags (we're not even using a list).
This is something you'll never encounter in everyday coding (unless you're among the lucky ones forced to work on an early '90s codebase), but will let us focus on the generic technic to be issued for our goal.

On the left there's our plain form, and on the right what we wanna achieve just applying a directive to every control in our template (we could design our directive to be applied on the form itself and issuing its logic for every child control, but let's keep it even simpler).

Here we got its template

<form [formGroup]="plainForm" (ngSubmit)="showSubmitObject()">
    <label>A text control</label><br>
    <input formControlName="text" selectablePlain><hr>
    <label>A number control</label><br>
    <input formControlName="number" type="number" selectablePlain><hr>
    <label>A radio control</label><br>
    <div>
        <label for="yes">Yes</label>
        <input formControlName="radio" type="radio" value="yes" id="yes">
        <label for="no">No</label>
        <input formControlName="radio" type="radio" value="no" id="no" selectablePlain>
    </div><hr>
    <label>A range control</label><br>
    <input formControlName="range" type="range" selectablePlain><hr>
    <label>A single selection control</label><br>
    <select formControlName="singleSel" selectablePlain>
        <option value="">--Please choose an option--</option>
        <option value="dog">Dog</option>
        <option value="cat">Cat</option>
        <option value="hamster">Hamster</option>
    </select><hr>
    <label>A multiple selection control</label><br>
    <select formControlName="multiSel" multiple selectablePlain>
        <option value="">--Please choose multiple options--</option>
        <option value="dog">Dog</option>
        <option value="cat">Cat</option>
        <option value="hamster">Hamster</option>
    </select><hr>
    <br>
    <button>Submit</button>
</form>

You can notice every control has been applied not only with the usual formControlName directive binding it to relative FormControl in code, but with a selectablePlain too: the selector for our directive that's gonna be.
Nothing else peculiar, I used most common types of control: text, number, radio, range, select and multi-select.
And here's its binding code

export class PlainControlsComponent {

  plainForm = new FormGroup({
    text: new FormControl(''),
    number: new FormControl(0),
    radio: new FormControl('no'),
    range: new FormControl(0),
    singleSel: new FormControl(''),
    multiSel: new FormControl([]),
  });
}

Visualize our goals

We can separate the expected functionalities of our directive in two tasks:

DOM manipulation: it should add an <input type="checkbox"> node just beside every template's controls elements
model alteration: formControls have to be enabled/disabled by user interaction with our checkboxes

While the latter is quite straightforward, because it's basically how every JS/TS framework's form interaction package is supposed to be used, the first one could present more than one issue to be implemented, even if in our purposely limited specific test case all the tricky aspects will be kept aside.

Show the code

Decorator definition and constructor injection:

@Directive({
  selector: '[selectablePlain]',
  standalone: true,
})
export class SelectablePlainDirective {

  constructor(
      private renderer: Renderer2,
      private hostEl: ElementRef,
      private ctrl: NgControl
  )

We set our selector to be used in template as selectablePlain, and in particular I declared this directive as standalone, new trend in Angular world (nothing would have changed declaring it in @NgModule like it was mandatory until Angular v14).
Then we inject some dependencies capable of executing our logic:

Renderer2: an Angular abstraction on top of WebAPI's Document and Node interfaces, providing some safe methods to programmatically manipulate DOM elements at low level.
ElementRef: injecting this class in a directive, we get access to an hosting element reference. In practice, we'll get in code an object wrapping DOM element to which directive is applied (<input>s or <select>s in our case)
NgControl: this class is common ancestor to NgModel, FormControlDirective and FormControlName, meaning that injecting it in place of any specific subclasses makes our directive more versatile and not dependent on the specific Form implementation the user chose for his template (having we bound every control with a formControlName directive, we would have obtained the same result injecting FormControlName class).

Constructor body

this.checkBox = this.renderer.createElement('input');
this.renderer.setAttribute(this.checkBox, 'type', 'checkbox');

Inside constructor body we use our Renderer2 instance to create the element to be added: we can see its createElement method accepting just the name of the tag to be generated.
After that, we leverage its setAttribute method to assign the type="checkbox" to this <input> element just created as per our needs.

this.renderer.insertBefore(
    this.renderer.parentNode(this.hostEl.nativeElement),
    this.checkBox,
    this.renderer.nextSibling(this.hostEl.nativeElement)
);

What looks like such a convoluted call, it's just a fill-in for a missing insertAfter method.
Leveraging our injected ElementRef, we retrieve our hosting element stored into its nativeElement property, and pass it to a couple of calls used as arguments of insertBefore.
This method is supposed to insert a new node as previous sibling of a target one, and expects three arguments:

parent of the target node
new node to be inserted
target node before which inserting new one

The trick is in the last one: we pass as target node the next sibling of our hosting element, leading renderer to actually put the new element between our hosting one and its next sibling (if any).

this.renderer.listen(
    this.checkBox,
    'change', 
    () => this.ctrl.disabled ? this.ctrl.control?.enable() : this.ctrl.control?.disable()
);

In the end, we attach a listener to our checkbox' change event, responsible of doing what is our real objective: if control is already disabled, a click on the checkbox should call enabling method, otherwise disable that.

ngOnInit for late setup

As this open ticket demonstrates, NgControl.control gets populated only after OnChange lifecycle, so every NgControl property related to runtime control values is undefined in constructor.
That's why we need to put part of our logic inside ngOnInit lifecycle callback.

if (this.ctrl.control?.enabled) 
  this.renderer.setProperty(this.checkBox, 'checked', true);

Here we're setting the initial checkbox state: we don't wanna see a checkbox associated to a control initially disabled appearing as checked, nor vice-versa.
So we check the initial status of our control, and set our checkbox' checked property accordingly.

this.ctrl.statusChanges?.pipe(
  tap((status: string) => status === "DISABLED" 
        ? this.renderer.setProperty(this.checkBox, 'checked', false)
        : this.renderer.setProperty(this.checkBox, 'checked', true)
  )
).subscribe()

Last thing missing is the guarantee that every programmatically change in control status will be reflected in related checkbox status: if some piece of TS code at some point disables our control, it would be misleading seeing its bound checkbox showing a flag as if it was still enabled.
To avoid this, we subscribe to NgControl.statusChanges observable, unchecking our checkbox everytime it emits a "DISABLED" value, and doing the opposite for everything else it should produce ("PENDING" | "VALID" | "INVALID").
Why we cannot rely on this for initial value too?
Because being it a status*Changes* emitter, it will not emit control's initial value.
But we are working in Angular after all, so we surely are confident with RxJs operators and know that startWith can do the trick here, so we fuse the last two snippets in a single one:

this.ctrl.statusChanges?.pipe(
  startWith(this.ctrl.control?.status),
  tap((status: string) => status === "DISABLED" 
        ? this.renderer.setProperty(this.checkBox, 'checked', false)
        : this.renderer.setProperty(this.checkBox, 'checked', true)
  )
).subscribe()

Now we can verify our controls are correctly disabled:

Conclusions

Final result is satisfying, but we need to keep in mind our testcase was tailored for the sake of the example.
If model interaction can be bent to work as expected most of the times, the same can't be said for DOM manipulation, where an initial template just a bit less smooth than the unrealistic one we used in this post can lead to totally different outputs.
Real cases turn the creation of a general-purpose directive into an extremely time-wasting exercise, with little to no advantage compared to manually adding needed checkboxes anywhere we need them, maybe enriching them with a pure model-oriented custom directive, specific for the case.
We'll get a taste of the issue in the next article, where we will try to replicate this task with an Angular Material styled form.

AnimationRenderer: listening and playing

Gianpiero Errigo — Mon, 02 Jan 2023 10:59:34 +0000

In the first two articles of this series we learned how AnimationRendererFactory generates its renderers.
Now we're gonna look at what "animating rendering transition" means concretely.

Animations: Transition vs Timeline

This series focuses on transition animations, declarative ones executed during state changes of an element.
There's another type of animation available in Angular: timeline animation ones, that can be explicitly issued after having built a dedicated player following the flow started by AnimationBuilder class.
These two flavours share big part of animation lifecycle but differ in some details, thus they need to notify their nature to common gears.
In the end they both rely on elements' properties for their job: transitions expecting to find them declared in templates, while programmatic ones translating command issued by the player in DOM nodes' properties.
To distinguish between the two, the framework defines a simple "contract":

transition animations properties will be prepended by a single @ character (explictly added by the coder during template writing, [@yourAnimationName]="yourCompProp")

timeline animations properties will automatically come prepended by two @@ characters by RendererAnimationPlayer.

function issueAnimationCommand(
renderer: AnimationRenderer, element: any, id: string, command: string, args: any[]): any {
return renderer.setProperty(element, `@@${id}:${command}`, args);
}

Even in this article we will not study timeline animations, but this preamble was due because at some point the classes we're going to examine will execute the checks to route flow in the right path.

AnimationRenderer overrides: entry points to animation flow

Our AnimationRendererFactory detected some triggers declared inside @Component metadata and generated an instance of AnimationRenderer.
Looking at the code, we notice that it extends the "dumb" BaseAnimationRenderer class covered in this series' first article.
It adds two important overrides: setProperty and listen.
First one is Renderer2's method to add/change DOM nodes' properties, that as we already explained, is the way the framework uses to trigger animation flow.
The latter instead, set an event listener on DOM nodes, and will be used by the framework to issue eventual callbacks we defined (for transition animations, think about start and done phases' output).

Let's see its constructor:

export class AnimationRenderer extends BaseAnimationRenderer implements Renderer2 {
  constructor(
      public factory: AnimationRendererFactory, namespaceId: string, delegate: Renderer2,
      engine: AnimationEngine, onDestroy?: () => void) {
    super(namespaceId, delegate, engine, onDestroy);
    this.namespaceId = namespaceId;
  }
  ...

It injects:

a reference to its factory, but this is only used for some kind of optimization we will not investigate in this article (here you can find relative commit, if you're curious).
the namespaceId uniquely identifying this renderer and extensively explained in previous article
a delegate *DOMRenderer for non-animated tasks
an AnimationEngine in charge of checking the nature of the animation and routing it to dedicated engine (TransitionAnimationEngine or TimelineAnimationEngine)
a destruction callback

That's all it needs to do its job.

setProperty(...): fire up this thing!

AnimationRenderer

We already told every animation starts with a change in the value of some dedicated DOM nodes properties, applied by AnimationRenderer's setProperty override:

override setProperty(el: any, name: string, value: any): void {
  if (name.charAt(0) == ANIMATION_PREFIX) {
    if (name.charAt(1) == '.' && name == DISABLE_ANIMATIONS_FLAG) {
      value = value === undefined ? true : !!value;
      this.disableAnimations(el, value as boolean);
    } else {
      this.engine.process(this.namespaceId, el, name.slice(1), value);
    }
  } else {
    this.delegate.setProperty(el, name, value);
  }
}

It accepts the expected arguments: the element to which applying the property, the name of the property and its value.
Let's examine its logic:

first it checks if property is actually an animation binding, verifying its name starts with an ANIMATION_PREFIX, namely a @ character. Otherwise, the call is passed to delegated native *DOMRenderer
if the binding turns out as an animation one, code will look for a disabling instruction, that could have been issued assigning to the node a property named @.disabled. So for optimization it first checks for a dot character . following @, and after that for the string disabled. If found, it will ask the engine to disable any animation for that element and its children
when the binding is an actual animation request instead, AnimationEngine' process method is called, passing as arguments:
- specific namespaceId
- the element
- name of the property stripped of its first @ character
- new value to be assigned to the property

AnimationEngine

Here's how AnimationEngine processes the call.
Remember that AnimationRenderer already stripped first @ char.

process(namespaceId: string, element: any, property: string, value: any) {
  if (property.charAt(0) == '@') {
    const [id, action] = parseTimelineCommand(property);
    const args = value as any[];
    this._timelineEngine.command(id, element, action, args);
  } else {
    this._transitionEngine.trigger(namespaceId, element, property, value);
  }
}

it immediately checks first character of the property name:
- if it's again a @ character, we are facing a timeline animations request, that as we already seen gets constructed with the structure @@${id}:${command}. Calling parseTimelineCommand, property name gets tokenized stripping remaining leading @ and using colon char : as separator, extracting id of the specific BrowserAnimationFactory and the name of the command to be executed. Value of the property (if any) gets passed as array of arguments to the command
- if received property's first character is anything but @, we're surely dealing with a transition animation, thus the code passes the request to TransitionAnimationEngine's trigger method, responsible of bootstrapping the logic of TransitionAnimationNamespace related method. This one, after a really complex logic aiming at collecting and enqueueing all possible involved animations on the elements of its pertinence, will call one or more TransitionAnimationPlayer.

listen(...): catch that animation event!

AnimationRenderer

Whatever the nature of our animation, we could have setup some operations to be executed just before or after the animation has been played (and in case of timeline animations, before or after player gets explicitly destroyed too).
To achieve this goal we assign callbacks to some listeners exposed by the framework.
For transition animations we can bind desired functions to some phase outputs in template, in the form (@yourAnimationName.start)="yourFunction()" or (@yourAnimationName.done)="yourFunction()".
A rule similar to the one we observed for setProperties has to be obliged:

transition animations events have to be prepended by a single @ character

timeline animations events will automatically come prepended by two @@ characters by RendererAnimationPlayer.

private _listen(eventName: string, callback: (event: any) => any): () => void {
return this._renderer.listen(this.element, `@@${this.id}:${eventName}`, callback);
}

These events will be caught by AnimationRenderer's listen method, that we're going to analyze:

override listen(
    target: 'window'|'document'|'body'|any, eventName: string,
    callback: (event: any) => any): () => void {
  if (eventName.charAt(0) == ANIMATION_PREFIX) {
    const element = resolveElementFromTarget(target);
    let name = eventName.slice(1);
    let phase = '';
    // @listener.phase is for trigger animation callbacks
    // @@listener is for animation builder callbacks
    if (name.charAt(0) != ANIMATION_PREFIX) {
      [name, phase] = parseTriggerCallbackName(name);
    }
    return this.engine.listen(this.namespaceId, element, name, phase, event => {
      const countId = (event as any)['_data'] || -1;
      this.factory.scheduleListenerCallback(countId, callback, event);
    });
  }
  return this.delegate.listen(target, eventName, callback);
}

It accepts three arguments:

target on which listen for the event
name of the event
function to be executed

Now, its logic:

first check is something we already saw on setProperty implementation: look at first character of the event name, if it doesn't start with a @ character, it's not an animation event, so its management can be passed to delegated native *DOMRenderer
target gets processed in case it comes as a string, and its respective HTML element gets returned (at least for transition animations I can't see when this can happen, considering listener is added by Angular template parser, and that window, document and body elements are outside its control. Whoever should know better is welcome in comments)
first @ character gets stripped from event name
first character of current name event (just stripped of the mandatory @ one) gets checked again, because:
- if it's not another @ char, it means we got a transition animation event, so we need to tokenize it:
  - on the left of dot character . we got our trigger name
  - on right side there's the name of its phase for which we want to register a listener
- if instead a second @ char is found, the name gets passed down the chain as-is, ditching manipulation task to AnimationEngine as we'll see later
now we're good to call AnimationEngine's listen method passing as its arguments:
- namespaceId proper of this renderer
- element resolved as explained
- name of the event (extracted from original one for transition animations, or completely cloned for timeline animations)
- name of the phase (again extracted, or just an empty string for timeline ones)
- a wrapper function around our real callback scheduling it on microtask, but for the sake of simplicity in this article we will consider as if it received just our callback directly

AnimationEngine

As for setProperty call chain,the role of AnimationEngine in even listening is just a little more than the one of a "router" to the correct specific engine:

listen(
    namespaceId: string, element: any, eventName: string, eventPhase: string,
    callback: (event: any) => any): () => any {
  // @@listen
  if (eventName.charAt(0) == '@') {
    const [id, action] = parseTimelineCommand(eventName);
    return this._timelineEngine.listen(id, element, action, callback);
  }
  return this._transitionEngine.listen(namespaceId, element, eventName, eventPhase, callback);
}

There's a check on event name's first character that we should used to, now:

if that's @, it means it has not been tokenized by caller AnimationRenderer's listen method and that we're processing a timeline animation event, so
- proceed to strip leading @
- split remaining string using colon : as separator to get id of the player and name of action to perform
- call dedicated TimelineAnimationEngine's listen method, that will take care of selecting right event's callback registered for specified player
otherwise we can pass it as-is as argument of TransitionAnimationEngine version of listen method, that after fetching the right AnimationTransitionNamespace instance by the namespaceId it received, will call its listen method, the one actually responsible of adding the listener to the array bound to that element.

I hope at this point the reader has at least a shallow understanding of transition animation registering flow in Angular.
I purposely left out some implementation details, and stopped digging down call chain before entering the real execution logic of players and callbacks, because that would have been confusing for you at least as much as it is for me.
My intent was to write just about concepts I correctly grasped but, as usual, I'm open to any review suggested in comments.

Thanks for reading!

Angular registering animation triggers

Gianpiero Errigo — Tue, 27 Dec 2022 11:11:48 +0000

This post keeps digging into AnimationRendererFactory creation routine, with a focus on triggers registering logic.

AnimationRenderer, the real one

Inside first article of this series we examined main concepts about Angular's AnimationRendererFactory and how it creates a "dumb" BaseAnimationRenderer to allow components not declaring any animation trigger to be known by the animation engine.

In this post we're going to analyze the creation process of a more interesting child class of the former renderer: AnimationRenderer.
An instance of this type is the one generated for components declaring one or more triggers inside their @Component decorator metadata animations property, which are needed to be registered with the engine before injecting the latter inside renderer constructor.

RendererType2: component's rendering metadata

We already seen factory's createRenderer expecting a type argument, declared as RendererType2.
This interface is defined to store some rendering information generated at component creation.

interface RendererType2 {
  id: string;
  encapsulation: ViewEncapsulation;
  styles: (string | any[])[];
  data: {[kind: string]: any};
}

If second and third ones remind you of some @Component decorator's metadata, that's because the framework takes their values exactly from there when creating a component, being it routed or a child one.
Let's examine them one by one:

id: this is an identifier generated by compiler for the specific Component class. Don't be fooled by misleading official doc definition: A unique identifying string for the new renderer. The assertion could let the reader think everytime he creates a new instance of the component, this will get a new id, but that's not true. The property has to be considered as a static class field: every instance of the same @Component class will get the same id. Official definition is not wrong per-se, but take in account only DomRendererFactory2, that for every instance of the same component will return the same cached renderer (at least for ViewEncapsulation.Emulated), making the id effectively unique for all EmulatedEncapsulationDomRenderer2 generated for that class, and obviously for the single instance of DefaultDomRenderer2 returned in some conditions. This definition loses its accountability when talking about AnimationRenderer, where two different instances of the same component will get assigned two different instances of the renderer, due to the introduction of namespace concept. (More about this later)
encapsulation: with this value DomRendererFactory2 choose which type of encapsulation-specific renderer to create, through a simple switch statement:

switch (type.encapsulation) {
  case ViewEncapsulation.Emulated: {
    ...
    renderer = new EmulatedEncapsulationDomRenderer2(
      this.eventManager, this.sharedStylesHost, type, this.appId);
    ...
    return renderer;
  }
  case ViewEncapsulation.ShadowDom:
    return new ShadowDomRenderer(this.eventManager, this.sharedStylesHost, element, type);
  default: {
    ...
    return this.defaultRenderer;
  }

styles: CSS style or list of styles to be assigned to host element of rendered component
data: this property shaped as an open dictionary could sound "alien", but it's actually the one used to define a whole set of optional characteristics of the component that's gonna be created. It's crucial for our case study because that's where AnimationRenderer will look for declared AnimationTriggerMetadata to be registered.

Namespace independently tracking state of component instances triggers

To keep track of individual component instances' triggers state, Angular animation package introduces the concept of AnimationTransitionNamespace.
You can think of it as a wrapper grouping all elements of a single animated component instance.
As already explained, id property from Renderer2 interface is unique for component's class, thus is not enough to distinguish among different instances of same component.
That's why the factory declares a new property, incremented on every AnimationRenderer creation, and concatenated with Renderer2's id to compose an identifier unique for namespace, used to register the latter with the engine:

const componentId = type.id;
const namespaceId = type.id + '-' + this._currentId;
this._currentId++;

this.engine.register(namespaceId, hostElement);

You can notice these identifiers added as a class to every DOM element of the host component: they are all prepended by ng-tns- string:

Look at the ng-tns-c19-8 class assigned to <app-home> element: this means that HomeComponent got c19 as its RendererType2.id, and that this specific instance has been bound to the ninth (_currentId is initialized as 0) AnimationRenderer created by the factory, which being injected as singleton make that number the creation order along the whole app.
(AFAIK, these identifiers have just a naming purpose, so their order should be of no interest.)

You can see that the same class has been added to everyone of its children, both <div> and <app-child> nodes.
But in the second a difference catches the eye:
another namespace class is assigned beside the parent's one, ng-tns-c18-9.
It's clear that this namespace refers to a different component class than the parent one (c-18 vs c-19).
That's expected, being <app-child> the host element of a different component.
Since ChildComponent's declares some triggers inside its decorator animations property, a new AnimationRenderer has been created for it, thus a new namespace.
So, being this component instance both declaring some animations, both included in the template of an animated parent component, it's part of two different namespaces.

Looking at third childnode, another <app-child> element, we notice that parent namespace class is still there, but its own namespace class is different than the one of its sibling: ng-tns-c18-10, same component type id but counter incremented by one.
This concurs with source code we analyzed earlier: even being instances of the same component class, they got separate renderers and are part of distinct namespaces.

Last thing worth noting is the inner elements of child host elements, in our example a <div> inside the expanded last <app-child>: it gets the namespace of component it belongs to, ng-tns-c18-10, but not the one of its grandparent, like its host element does.
This sounds quite logical, considering that <app-child> is included into HomeComponent's template, while child nodes inside its own template are not.

Actual registration of triggers

On top of the source file declaring this factory, we got a couple of type declarations (a type and an interface, to be precise)

// Define a recursive type to allow for nested arrays of `AnimationTriggerMetadata`. Note that an
// interface declaration is used as TypeScript prior to 3.7 does not support recursive type
// references, see https://github.com/microsoft/TypeScript/pull/33050 for details.
type NestedAnimationTriggerMetadata = AnimationTriggerMetadata|RecursiveAnimationTriggerMetadata;
interface RecursiveAnimationTriggerMetadata extends Array<NestedAnimationTriggerMetadata> {}

They look quite tricky at first sight, but reading accompanying comment and analyzing their definitions, it turns out they just form a recursive data structure.
Their use, as we're gonna see, addresses a problem arisen switching from ViewEngine to Ivy, with the new one losing the capabilities of flattening metadata arrays, resulting in wrong registering of triggers passed to @Component as nested arrays, leading to runtime errors.

Compiler parsed our @Component decorators metadata and stored their animations field content inside animation property of aforementioned data open-dictionary field of related RendererType2 object.
Renderer creation routine casts this value to an array of the recursive data structure we already seen has been defined on purpose.
Then it iterates over that, issuing a registration function for every trigger it finds.

const animationTriggers = type.data['animation'] as NestedAnimationTriggerMetadata[];
animationTriggers.forEach(registerTrigger);

This registering function has to take in account the recursive nature of this data structure: the object it gets passed as argument could be an actual trigger to be registered, or an array itself containing triggers definitions, and even an array containing other arrays. This nesting has an unpredictable depth, so our function has to be implemented with a recursive logic.

const registerTrigger = (trigger: NestedAnimationTriggerMetadata) => {
  if (Array.isArray(trigger)) {
    trigger.forEach(registerTrigger);
  } else {
    this.engine.registerTrigger(componentId, namespaceId, hostElement, trigger.name, trigger);
  }
};

We can see it's a common flattening algorithm often used with recursively nested arrays: a function recalling itself until its argument is proved to be an array, when this check fails we are in presence of a trigger definition to be registered with engine (and in turn with specific namespace).

When all defined triggers have been registered, a new AnimationRenderer can be built and returned, injected with the namespaceId composed in previous phase.

Hope this post has been an interesting reading, and since the topic has still many "obscure" details for me, I encourage anyone with a constructive suggestion to get in touch in comments.
Next time we'll take a look at AnimationRenderer actual work.
Cheers.

AnimationFactory: how Angular creates animation renderers

Gianpiero Errigo — Tue, 20 Dec 2022 11:08:14 +0000

This article is intended to be the beginning of a short series about Angular transition animations mechanism source code, a niche in Angular codebase often considered confusing and not enough documented.

Angular transition animations

For "Transition Animations" in Angular we mean adding transitioning effects between elements' state changes.
Normally this is done by binding a trigger to a property that will get the values of the states whose transition we want to animate.
They share only last part of their flow with "Timeline Animations", the ones executed by explicitly operating Animation Players, and that will not be a topic of these articles.

Quick recap on Angular Renderers

To manipulate the DOM without directly accessing its nodes Angular leverages Renderers, tools designed to be a level of abstraction on native DOM operations.
They're shaped upon abstract class Renderer2, and are fundamental in transition animations context because some of their flavors get used to start animation flow.
They get not instanciated manually, but generated by a RendererFactory2.

Animations module

First step to start using animations is importing BrowserAnimationsModule.
This module, among other things, will provide some concrete implementations of aforementioned abstract classes, adding animation capabilities to component creation logic.
Above all, it will ship AnimationRendererFactory that, together with some Renderer implementations it's capable to return, will supersede the ones provided by BrowserModule.
(For the sake of simplicty this series will take in account only the Browser platform, used to build webapps).

export function instantiateRendererFactory(
    renderer: DomRendererFactory2, engine: AnimationEngine, zone: NgZone) {
  return new AnimationRendererFactory(renderer, engine, zone);
}

const SHARED_ANIMATION_PROVIDERS: Provider[] = [
  {provide: AnimationBuilder, useClass: BrowserAnimationBuilder},
  {provide: AnimationStyleNormalizer, useFactory: instantiateDefaultStyleNormalizer},
  {provide: AnimationEngine, useClass: InjectableAnimationEngine}, {
    provide: RendererFactory2,
    useFactory: instantiateRendererFactory,
    deps: [DomRendererFactory2, AnimationEngine, NgZone]
  }
];

AnimationRendererFactory creating animation renderer

The gist of this factory is that it gets injected with an AnimationEngine used by its generated renderers to enrich DOM operations with animated effects.

@Injectable()
export class AnimationRendererFactory implements RendererFactory2 {
  ...
  constructor(
      private delegate: RendererFactory2, private engine: AnimationEngine, private _zone: NgZone)

Another important dependency passed to its constructor, is the property called delegate typed as RendererFactory2, populated with an instance of DomRendererFactory2.
This is an implementation of Delegation Pattern used to compose an enhanced RendererFactory.
Normal non-animated DOM operations will be delegated to the original DefaultDomRenderer2 instances generated by this delegate factory, while the new delegator animated renderers will take care of animation tasks only.

Being this class a factory of renderers, its main functionalities reside in createRenderer method.
It accepts two arguments:

the hostElement being the "first ancestor" of all the elements included in our template (think of the element identified by your component's selector)
a type typed as RendererType2 (I know... sorry), an object storing some rendering information, mostly retrieved from your @Component decorator's metadata.

Looking at its early lines we can understand how a basic animation renderer is created for components not registering any animation.

createRenderer(hostElement: any, type: RendererType2): Renderer2 {
  const EMPTY_NAMESPACE_ID = '';

  // cache the delegates to find out which cached delegate can
  // be used by which cached renderer
  const delegate = this.delegate.createRenderer(hostElement, type);
  if (!hostElement || !type || !type.data || !type.data['animation']) {
    let renderer: BaseAnimationRenderer|undefined = this._rendererCache.get(delegate);
    if (!renderer) {
      // Ensure that the renderer is removed from the cache on destroy
      // since it may contain references to detached DOM nodes.
      const onRendererDestroy = () => this._rendererCache.delete(delegate);
      renderer =
          new BaseAnimationRenderer(EMPTY_NAMESPACE_ID, delegate, this.engine, onRendererDestroy);
      // only cache this result when the base renderer is used
      this._rendererCache.set(delegate, renderer);
    }
    return renderer;
  }

first it uses the factory delegate to generate a pure "animation-unaware" DOMRenderer and store it as a local delegate variable (don't get confused: global delegate this.delegate refers to factory delegate, while (unfortunately) homonymous local const delegate point to the newly generated renderer delegate)
it checks for any trigger listed inside animations property of @Component's decorator (after verifying the creation request is not relative to an hostRenderer, but this detail is beyond the scope of this article), and the branch entered when it can't find anyone is the one we're investigating
looks inside factory cache for an AnimationRenderer bound to the DOMRenderer just created (delegate DomRendererFactory2 is capable of returning cached DOMRenderer too, so the "created" could be a reference to an already existing one, thus giving a match in strict equality lookup used by JS for Map.prototype)
if not found, creates a new one (injected with freshly created renderer delegate, and with a cache cleanup callback to be issued on renderer destruction), adds that to cache and returns it

Little work for BaseAnimationRenderer

Looking at BaseAnimationRenderer code we notice how for most of its implementations it merely calls the corresponding delegated renderer methods, aside from elements insertions and deletions related ones.

export class BaseAnimationRenderer implements Renderer2 {
  constructor(
      protected namespaceId: string, public delegate: Renderer2, public engine: AnimationEngine,
      private _onDestroy?: () => void)

  ...

  appendChild(parent: any, newChild: any): void {
    this.delegate.appendChild(parent, newChild);
    this.engine.onInsert(this.namespaceId, newChild, parent, false);
  }

  insertBefore(parent: any, newChild: any, refChild: any, isMove: boolean = true): void {
    this.delegate.insertBefore(parent, newChild, refChild);
    // If `isMove` true than we should animate this insert.
    this.engine.onInsert(this.namespaceId, newChild, parent, isMove);
  }

  removeChild(parent: any, oldChild: any, isHostElement: boolean): void {
    this.engine.onRemove(this.namespaceId, oldChild, this.delegate, isHostElement);
  }

This seems to be needed by deep layers of animation module to mark the elements as removed or inserted even in absence of a visible transition, mainly for move operations.
More interesting are the overrides of its child class AnimationRenderer, instanciated by the factory when the component that's gonna be created declares some animation triggers.
Both trigger registrations and added functionalities will be covered in following articles.

Thanks for reading, and feel free to get in touch in comments for every question, correction, clarification or opinion.

DEV Community: Gianpiero Errigo

Angular 15: what happened to environment.ts

TL;DR: Nothing!

A misunderstood purpose

Original role

Black magic of file replacement

What changed in version 15

Why people are freaking out

Lazy solution

Why they didn't think of that before

Nx Module Federation bad Angular routing

The issue

The reason

My solution

Conclusions

Duplicate entry component rendering for standalone ng component served as independent frontend #14551

Current Behavior

Expected Behavior

Github Repo

Steps to Reproduce

Nx Report

Failure Logs

Additional Information

Material forms: mat-checkbox disabling controls

Recap our goals

Replacing plain checkbox with fancy mat-checkbox: nice, but...

How it should be: <mat-form-field>

Outside <mat-form-field> things start to branch

The sore point: <mat-slider>

Conclusions

Angular forms: checkbox disabling controls

How to write a directive to add it.

And why you shouldn't.

Useless harness

Visualize our goals

Show the code

Decorator definition and constructor injection:

Constructor body

ngOnInit for late setup

Conclusions

AnimationRenderer: listening and playing

Animations: Transition vs Timeline

AnimationRenderer overrides: entry points to animation flow

setProperty(...): fire up this thing!

AnimationRenderer

AnimationEngine

listen(...): catch that animation event!

AnimationRenderer

AnimationEngine

Angular registering animation triggers

AnimationRenderer, the real one

RendererType2: component's rendering metadata

Namespace independently tracking state of component instances triggers

Actual registration of triggers

AnimationFactory: how Angular creates animation renderers

Angular transition animations

Quick recap on Angular Renderers

Animations module

AnimationRendererFactory creating animation renderer

Little work for BaseAnimationRenderer

Replacing plain checkbox with fancy `mat-checkbox`: nice, but...

How it should be: `<mat-form-field>`

Outside `<mat-form-field>` things start to branch

The sore point: `<mat-slider>`