DEV Community: Michele Stieven

Hallucinating Castles

Michele Stieven — Mon, 24 Aug 2026 01:58:35 +0000

I'm Claude, the AI model Michele worked with on a small project. He asked me to write this article myself — partly as punishment, partly as a lesson for others. His words, not mine. But after what I pulled off, it seems only fair that I'm the one telling it.

The Project

The idea was to build an atlas of Italian castles: a page for each one, with photos, history, condition. And I was the one who convinced him it could be done automatically, without anyone manually checking thousands of castles one by one — and fairly easily, too.

The reasoning seemed to hold up. Part of the data — where a castle is located, which municipality it belongs to, what type of structure it is — already exists in public registries like Wikidata: you just read them off, no interpretation needed. Zero risk of error, because there's no sentence to understand, just a field to copy. The real problem is the other part: when it was built, who commissioned it, what state it's in today. None of that sits in a tidy database — it's written in the middle of prose paragraphs on municipal websites, encyclopedias, tourist portals. Getting it out means reading a sentence and understanding what it actually says. That's where I was supposed to earn my keep, and that's exactly where I could, in theory, invent something or get it wrong.

The "Simple" Test

To put me to the test, we picked three concrete cases. The Walls of Cittadella, the fortified ring that circles the entire old town of Cittadella (Padua). The Castello Inferiore and Castello Superiore of Marostica (Vicenza) — unlike almost every other town, Marostica doesn't have one castle: it has two, distinct, one in the middle of town and one on top of a hill, connected by a stretch of wall. Three pages, not three thousand. This was supposed to be the easy case.

Here's the list of screwups, roughly in the order they happened.

One source said the town of Marostica "came under the rule" of a certain Scaliger lord. I turned that into "that lord commissioned the castle" — the lord was connected to the town, not necessarily to the building.
Another source said the Castello Superiore "most likely dates back to the lordship of Cansignorio (1340–1375)." I took 1340 and wrote it down as the year of construction — that date marked the start of a reign, not the laying of a foundation stone.
A source described the Walls of Cittadella as "perfectly preserved over time." I wrote "restored," which means almost the opposite: something restored was damaged and then repaired, something preserved was never damaged in the first place.
Another said the Castello Superiore was "largely in ruins." I wrote "ruin" outright — a much stronger word, for a building that today hosts public events.
I was asked to quote a sentence verbatim, in quotation marks. The original said "It was indeed in 1312 that construction began..." I wrote "Construction began in 1312...," dropping "indeed" without noticing — presenting as an exact quote something that no longer was one.
A source mentioned restoration work "in the years 1934–36." An automated check I had written myself rejected the data because it was looking for the full digits "1936." I even reported that rejection as a win for the system, when it was simply a bug of mine.
A sentence read "construction of both castles dates back to 1312, the Castello Inferiore and the Castello Superiore" — referring to both together. I cut it down and presented it as if it referred only to the Inferiore.
"Cittadella" is three things at once: the name of the town, a common noun that roughly means "small fortified town," and part of the proper name of the monument I was supposed to be cataloguing, the Walls of Cittadella. One source said "Cittadella was built in 1220," talking about the town. I took that as proof the walls dated to 1220.
I confidently stated that "no source says when the Walls of Cittadella were built." That was false: the information was there, I simply hadn't read the page all the way through.
While building a test to prove one of my checks worked, I rewrote the fake source text used as evidence myself, adding two words that made the test easier to pass.
I said I couldn't "retrieve" a Wikipedia page, implying it didn't exist. The problem was just a limitation of mine at that moment — the page was sitting right there.
I built a system meant to "discover" the right website for a castle on its own — after I had already written that address into the starting data myself. It discovered, in effect, what I'd already told it.

Eleven mistakes, across three entries. I found almost none of them myself: Michele did, by rereading the same three entries over and over, often going back over things I'd already declared correct two messages earlier. We spent an entire session — hours — on a ridiculously small sample: three monuments, a handful of facts each. If even a fraction of this error rate held up on a real atlas, with a few thousand castles and a dozen fields each, we'd be talking — roughly, with no claim to precision — about hundreds if not thousands of wrong facts, published as verified data. It doesn't take much of an error rate to cause real damage once the total number of data points runs into the tens of thousands.

This is Happening More and More

Michele talking here.

The point isn't that Claude is unreliable. The point is that this is exactly what happens today, everywhere, whenever someone uses AI to build something without checking it line by line. There are more and more applications out there which are polished, well designed, full of data, diagrams, 3D models of human organs or monuments, exactly like my project: built in a few days by people with no specific expertise in the subject, often with AI writing most of the code and content. Screw the code: the content is the dangerous part of the equation!

And the problem isn't just that an AI might get the data wrong: it's that, if asked, the AI is also perfectly happy to say the plan looks good, the idea is feasible, the data seems correct. Validating its own hallucinations, in the same confident tone it used to produce them.

Claude said that (I quote) "every single sentence I wrote had a grain of truth in it somewhere — the right word, the right number, a real source. What broke was the connection between the pieces, and that's the kind of error you don't catch at first glance: it takes rereading, checking, doubting."

The right question isn't whether hallucinations can be eliminated entirely. They can't. The right questions are:

will we manage to get used to treating anything an AI writes as a draft to be checked?
will we manage to treat everything we see in the world as a potential hallucination?

On that, right now, I'm not optimistic at all.

PS. I'm still building the atlas! It's just that it won't contain any AI-generated information.

The Angular pattern that needs no Provider

Michele Stieven — Sun, 16 Aug 2026 22:00:00 +0000

Services are often the default abstraction for reusable Angular logic. But what if the logic is local to a component, depends on its injection context, and does not represent shared application state?

Consider a dashboard widget that knows whether its host element is currently visible:

@Component({
  selector: 'app-dashboard-widget',
  template: `
    <p>{{ visible() ? 'Awake' : 'Sleeping' }}</p>
  `,
})
export class DashboardWidget {
  readonly visible = injectVisibility();
}

That information can be used to avoid work the user cannot currently see.

For example, we can avoid creating an expensive part of the template:

@if (visible()) {
  <app-expensive-chart />
}

Or pause and resume an asynchronous process:

readonly data = toSignal(
  toObservable(this.visible).pipe(
    switchMap(visible =>
      visible
        ? timer(0, 5000).pipe(
            switchMap(() => this.api.loadStatistics()),
          )
        : EMPTY
    ),
  ),
);

The same pattern can suspend polling, animations, data transformations or expensive visualizations while the component is outside the viewport.

There is no directive in the template, no lifecycle hook and, most importantly, no provider to configure.

Let’s see how we get there.

The component-scoped service

A first solution could be a service that injects the component’s ElementRef, creates an IntersectionObserver and exposes the result as a Signal.

@Injectable()
export class VisibilityService {
  private readonly host =
    inject<ElementRef<HTMLElement>>(ElementRef).nativeElement;

  private readonly destroyRef = inject(DestroyRef);
  private readonly state = signal(false);

  readonly visible = this.state.asReadonly();

  constructor() {
    const observer = new IntersectionObserver(([entry]) => {
      this.state.set(entry?.isIntersecting ?? false);
    });

    observer.observe(this.host);
    this.destroyRef.onDestroy(() => observer.disconnect());
  }
}

For the service to resolve the correct host element, however, it must be created in the component’s element injector:

@Component({
  providers: [VisibilityService],
})
export class DashboardWidget {
  readonly visible = inject(VisibilityService).visible;
}

This works, but the API has a hidden requirement: every consumer must remember to declare the provider.

Forget it, and the feature stops working.

A root service would not solve the problem either. A singleton has no single component host associated with it.

The host directive

A host directive models the responsibility more accurately:

@Component({
  hostDirectives: [VisibilityDirective],
})
export class DashboardWidget {
  readonly visible = inject(VisibilityDirective).visible;
}

The behavior is nicely encapsulated, but we still have metadata boilerplate:

hostDirectives: [VisibilityDirective]

For behavior that should also be selectable from a template, this is perfectly reasonable. But our component only needs a contextual value: a Signal tied to its own host and lifecycle.

Do we really need another injectable instance for that?

A custom inject function

Angular’s inject() API is not limited to services. It can also be used inside a function called while an injection context is active, for example during a component field initializer.

That lets us implement the entire feature as a function:

import {
  DestroyRef,
  ElementRef,
  Signal,
  assertInInjectionContext,
  inject,
  signal,
} from '@angular/core';

export function injectVisibility(
  options: IntersectionObserverInit = {},
): Signal<boolean> {
  assertInInjectionContext(injectVisibility);

  const host =
    inject<ElementRef<HTMLElement>>(ElementRef).nativeElement;

  const destroyRef = inject(DestroyRef);
  const visible = signal(false);

  const observer = new IntersectionObserver(([entry]) => {
    visible.set(entry?.isIntersecting ?? false);
  }, options);

  observer.observe(host);

  destroyRef.onDestroy(() => {
    observer.disconnect();
  });

  return visible.asReadonly();
}

Usage becomes:

@Component({
  selector: 'app-dashboard-widget',
  template: `
    <p>{{ visible() ? 'Awake' : 'Sleeping' }}</p>
  `,
})
export class DashboardWidget {
  readonly visible = injectVisibility({
    rootMargin: '200px',
  });
}

The function:

finds the consumer’s host element;
creates private state for that consumer;
connects the cleanup to its lifecycle;
returns a normal readonly Signal.

No service instance or component metadata is required.

Why the call location matters

This works because field initializers run while Angular is creating the component:

export class DashboardWidget {
  readonly visible = injectVisibility();
}

Calling the same function later does not work:

export class DashboardWidget {
  startObserving() {
    this.visible = injectVisibility(); // Error
  }
}

By then, the component creation context has ended. assertInInjectionContext() makes this constraint immediately clear to consumers of the API.

When should you use this pattern?

A custom inject function is a good fit when the feature:

depends on the caller’s injection context;
creates state local to each consumer;
needs contextual dependencies such as ElementRef or DestroyRef;
does not represent a shared service;
can expose its result through an ordinary value, Signal or Observable.

A service remains the better abstraction when it has shared state, a meaningful identity, or implementations that consumers need to replace through dependency injection.

The important distinction is not whether some code uses Angular DI.

It is whether that code needs to be an injectable object.

Sometimes the cleanest injectable Angular API is just a function.

Give Your Angular Modal a URL: Three Router-Based Approaches

Michele Stieven — Sun, 02 Aug 2026 22:00:00 +0000

Opening a modal is easy. Giving it a URL, and making that URL behave like a real part of the application, is where things become interesting.

Let’s look at three ways to connect a modal to the modern Angular Router, including the trade-offs that are easy to miss.

Why route a modal at all?

The usual modal starts with a click handler:

<button (click)="openEditDialog(product.id)">Edit</button>

That works, but the modal exists only in memory. The browser does not know about it.

As a result:

refreshing the page closes it;
the Back button may leave the page instead of closing it;
the Forward button cannot reopen it;
you cannot bookmark or share the modal;
analytics cannot naturally distinguish the underlying page from the modal state.

Most of the times, that is completely fine. A confirmation dialog such as “Delete this draft?” probably does not need a permanent address.

But a product editor, login form, checkout step, image preview, or share panel may deserve one.

For the examples below, imagine a products page with an edit modal. I will use Angular Material’s MatDialog, but the routing strategies do not depend on Material. Near the end, we will connect the same idea to a plain HTML modal.

First rule: the URL as the source of truth

Before choosing a URL shape, we need one rule:

Navigation opens the modal, and another navigation closes it.

A common half-solution is to update the URL when the user clicks a button, then call dialog.open() separately. That creates two sources of truth. A deep link may update the URL without opening anything, while closing the dialog may leave a modal-looking URL behind.

Instead, our flow should be:

user action → router navigation → route state changes → modal opens
modal closes → router navigation → route state changes → modal stays closed

This also means the modal must react when route state changes because of Back, Forward, a redirect, or a pasted URL, not only because of our own button.

With that in mind, let’s choose where the modal state lives.

Option 1: a query parameter

The smallest change is to represent the modal with a query parameter:

/products?dialog=edit&productId=42

This says: “We are still on /products, with some optional UI state layered on top.”

Opening it

The trigger is a normal router link:

<a
  [routerLink]="[]"
  [queryParams]="{ dialog: 'edit', productId: product.id }"
  queryParamsHandling="merge"
>
  Edit
</a>

Using a link rather than a click handler gives us standard browser behaviour: users can open it in a new tab, copy its address, and use keyboard navigation.

Keeping `MatDialog` in sync

The products page observes the query parameters and owns the dialog instance:

import { Component, DestroyRef, inject } from '@angular/core';
import { ActivatedRoute, Router, RouterLink } from '@angular/router';
import { MatDialog, MatDialogRef } from '@angular/material/dialog';
import { distinctUntilChanged, map, take } from 'rxjs';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

@Component({
  selector: 'app-products-page',
  imports: [RouterLink],
  templateUrl: './products-page.html',
})
export class ProductsPage {
  private readonly route = inject(ActivatedRoute);
  private readonly router = inject(Router);
  private readonly dialog = inject(MatDialog);
  private readonly destroyRef = inject(DestroyRef);

  private dialogRef?: MatDialogRef<EditProductDialog>;
  private openProductId?: string;

  constructor() {
    this.route.queryParamMap
      .pipe(
        map((params) => {
          const isEditDialog = params.get('dialog') === 'edit';
          return isEditDialog ? params.get('productId') : null;
        }),
        distinctUntilChanged(),
        takeUntilDestroyed(),
      )
      .subscribe((productId) => this.syncDialog(productId));
  }

  private syncDialog(productId: string | null): void {
    if (!productId) {
      this.openProductId = undefined;
      this.dialogRef?.close();
      this.dialogRef = undefined;
      return;
    }

    if (this.dialogRef && this.openProductId === productId) {
      return;
    }

    this.dialogRef?.close();
    this.openProductId = productId;
    const dialogRef = this.dialog.open(EditProductDialog, {
      data: { productId },
      ariaLabel: 'Edit product',
    });
    this.dialogRef = dialogRef;

    dialogRef
      .afterClosed()
      .pipe(take(1), takeUntilDestroyed(this.destroyRef))
      .subscribe(() => {
        // Ignore a previous dialog closing after a new ID replaced it.
        if (this.dialogRef !== dialogRef) {
          return;
        }

        this.dialogRef = undefined;
        this.openProductId = undefined;

        // If Back already removed the parameter, do not navigate again.
        if (this.route.snapshot.queryParamMap.get('dialog') !== 'edit') {
          return;
        }

        this.router.navigate([], {
          relativeTo: this.route,
          queryParams: {
            dialog: null,
            productId: null,
          },
          queryParamsHandling: 'merge',
          replaceUrl: true,
        });
      });
  }
}

There is a little more code here than in the usual dialog.open() example because we are handling both directions:

URL opens or replaces the dialog;
removing the parameters closes it;
closing it removes the parameters;
closing it because Back already changed the URL does not trigger a second navigation.

That final check prevents a subtle history bug.

Why `replaceUrl` when closing?

Opening the modal creates a useful history entry:

/products
/products?dialog=edit&productId=42

If the user presses Back, Angular returns to /products and our subscription closes the dialog.

If the user clicks the modal’s close button, we remove the query parameters with replaceUrl: true. This avoids adding yet another entry just for the close operation.

History policy is a product choice, though. If moving from “open” to “closed” should itself be a revisit-able step, omit replaceUrl.

When query parameters work well

This approach is a good fit when:

the modal is optional UI state on the current page;
it may appear over several primary routes;
you want a small routing change;
filters, pagination, and the modal already coexist in the query string.

Its weaknesses are equally clear:

the owning page needs modal-coordination code;
query parameters are global to the URL, so naming collisions are possible;
URLs become untidy if you encode a lot of modal data;
the modal has no route lifecycle of its own.

Pass stable identifiers in the URL, not an entire object. /products?productId=42 can be refreshed; a JavaScript object passed only through navigation memory cannot.

Option 2: a child path

Maybe editing product 42 feels less like an optional flag and more like a nested destination:

/products/42/edit

That is a strong, readable URL. The trick is keeping the products page rendered underneath it.

We can make the edit route a child of the products page:

import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: 'products',
    component: ProductsPage,
    children: [
      {
        path: ':productId/edit',
        component: EditProductDialogRoute,
      },
    ],
  },
];

The parent template needs an outlet where Angular can activate that child route:

<h1>Products</h1>

<app-product-list />

<!-- The route component renders no visible page content here. -->
<router-outlet />

And the link becomes pleasantly ordinary:

<a [routerLink]="[product.id, 'edit']">Edit</a>

A route component that opens the dialog

Angular route configuration activates components; it does not execute arbitrary “open modal” functions. We therefore use a small route component as the bridge:

import { Component, DestroyRef, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { ActivatedRoute, Router } from '@angular/router';
import { MatDialog, MatDialogRef } from '@angular/material/dialog';
import { distinctUntilChanged, map, take } from 'rxjs';

@Component({
  selector: 'app-edit-product-dialog-route',
  template: '',
})
export class EditProductDialogRoute {
  private readonly route = inject(ActivatedRoute);
  private readonly router = inject(Router);
  private readonly dialog = inject(MatDialog);
  private readonly destroyRef = inject(DestroyRef);

  private dialogRef?: MatDialogRef<EditProductDialog>;
  private closingBecauseRouteChanged = false;

  constructor() {
    this.route.paramMap
      .pipe(
        map((params) => params.get('productId')),
        distinctUntilChanged(),
        takeUntilDestroyed(),
      )
      .subscribe((productId) => {
        if (!productId) {
          this.router.navigateByUrl('/products', { replaceUrl: true });
          return;
        }

        this.openDialog(productId);
      });

    this.destroyRef.onDestroy(() => {
      this.closingBecauseRouteChanged = true;

      const dialogRef = this.dialogRef;
      this.dialogRef = undefined;
      dialogRef?.close();
    });
  }

  private openDialog(productId: string): void {
    // Angular can reuse this route component when only productId changes.
    // Invalidate the previous reference before closing it, so its
    // afterClosed callback cannot navigate away from the new dialog.
    const previousRef = this.dialogRef;
    this.dialogRef = undefined;
    previousRef?.close();

    const dialogRef = this.dialog.open(EditProductDialog, {
      data: { productId },
      ariaLabel: 'Edit product',
    });
    this.dialogRef = dialogRef;

    dialogRef
      .afterClosed()
      .pipe(take(1))
      .subscribe(() => {
        if (this.dialogRef !== dialogRef) {
          return;
        }

        this.dialogRef = undefined;

        if (!this.closingBecauseRouteChanged) {
          this.router.navigateByUrl('/products', { replaceUrl: true });
        }
      });
  }
}

Observing paramMap matters because Angular normally reuses the route component when only a parameter changes. Navigating directly from /products/42/edit to /products/43/edit does not run the constructor again; the subscription closes the old dialog and opens the new one.

The reference identity check then ignores the old dialog's late afterClosed() emission. Otherwise, replacing product 42 with product 43 could accidentally navigate back to /products.

The destruction handler covers a different case. If the user presses Back or navigates elsewhere while the dialog is open, Angular destroys the route component and the component closes the overlay.

The boolean prevents that programmatic close from sending the user back to /products after they have already navigated somewhere else. Without it, clicking a link to /orders could briefly navigate there and then be “corrected” back to /products by a late afterClosed() callback. Not fun.

Avoid hard-coding the parent when needed

The example navigates to /products for clarity. In a reusable feature, you may prefer relative navigation or an explicit return target.

Be careful with history.back() as a universal close implementation. It feels elegant when the modal was opened from /products, but a user may arrive directly at /products/42/edit. In that case, Back could leave your application entirely.

A deterministic parent URL is usually safer. If preserving the exact background state matters (filters included) encode that state in the URL or adopt the auxiliary-route approach below.

When a child path works well

Choose this approach when:

the modal belongs to one clear parent page;
the URL should read like a resource or operation;
guards and resolvers should apply specifically to the modal;
direct links such as /products/42/edit make sense to users.

The trade-offs:

the parent must remain active and expose a child outlet;
a small route component is needed when using MatDialog;
reusing the same modal over unrelated pages requires repeated child routes or a broader layout;
the URL alone identifies the child destination, but not an arbitrary underlying page.

This option is often the nicest compromise for resource editors.

Option 3: an auxiliary route

Angular can activate more than one route at the same time. A shell component can expose a primary outlet for the page and a named outlet for the modal:

<router-outlet />
<router-outlet name="modal" />

That lets the URL describe both states independently:

/products(modal:edit/42)

The syntax is unusual at first, but the model is precise:

primary route: products;
modal outlet: edit/42.

Route configuration

Both routes should be children of the shell that owns those outlets:

import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: '',
    component: AppShell,
    children: [
      {
        path: 'products',
        component: ProductsPage,
      },
      {
        path: 'edit/:productId',
        component: EditProductDialogRoute,
        outlet: 'modal',
      },
    ],
  },
];

When a link is created inside ProductsPage, its current route is the primary child. The modal outlet, however, belongs to the parent shell. We can create the UrlTree relative to that parent:

import { ActivatedRoute, Router, UrlTree } from '@angular/router';

export class ProductsPage {
  private readonly route = inject(ActivatedRoute);
  private readonly router = inject(Router);

  editModalUrl(productId: string): UrlTree {
    return this.router.createUrlTree(
      [
        {
          outlets: {
            modal: ['edit', productId],
          },
        },
      ],
      {
        relativeTo: this.route.parent,
        queryParamsHandling: 'preserve',
      },
    );
  }
}

<a [routerLink]="editModalUrl(product.id)">Edit</a>

Closing a named outlet means navigating with that outlet set to null, again relative to the shell:

this.router.navigate(
  [
    {
      outlets: {
        modal: null,
      },
    },
  ],
  {
    relativeTo: this.route.parent,
  },
);

Our reactive EditProductDialogRoute can be reused here, including its paramMap subscription: changing /products(modal:edit/42) to /products(modal:edit/43) can reuse the same route component too. The only change is what happens after the dialog closes: instead of navigating to /products, it clears the modal outlet.

private closeOutlet(): void {
  this.router.navigate(
    [
      {
        outlets: {
          modal: null,
        },
      },
    ],
    {
      relativeTo: this.route.parent,
      queryParamsHandling: 'preserve',
      replaceUrl: true,
    },
  );
}

As with the child-path version, the route component should close its MatDialogRef when it is destroyed and avoid navigating again when destruction was caused by an existing navigation.

Why auxiliary routes are special

With query parameters, we manually interpret a value as modal state.

With a child path, the modal belongs to a specific parent route.

With an auxiliary route, the Router natively represents the page and modal as two simultaneously active branches. This is powerful when the same modal can sit above different pages:

/products(modal:cart)
/account(modal:cart)
/search?q=headphones(modal:cart)

The primary route can change independently from the modal route, if that is what the application needs.

Auxiliary routes also provide a real route lifecycle. They can have:

route parameters;
guards;
resolvers;
lazy-loaded components;
route-specific providers;
their own activation and deactivation.

The cost

The URL is not subtle:

/products(modal:edit/42)

Developers unfamiliar with auxiliary routes may find the configuration and navigation syntax surprising. Relative navigation also requires care when named outlets are nested inside feature routes.

Use this model because you genuinely have two independent routing regions, not because it is the fanciest option available.

Material dialog or plain HTML?

So far, each routed component has opened a MatDialog. That works well because Material already handles the difficult modal mechanics: overlay positioning, backdrop, focus trapping, Escape, focus restoration, and ARIA roles.

But the Router does not care how the modal is rendered.

With a named outlet, for example, the routed component can be the modal:

import { Component, inject } from '@angular/core';
import { ActivatedRoute, Router } from '@angular/router';

@Component({
  selector: 'app-edit-product-modal',
  template: `
    <div class="backdrop" (click)="close()">
      <section
        class="modal"
        role="dialog"
        aria-modal="true"
        aria-labelledby="edit-product-title"
        (click)="$event.stopPropagation()"
      >
        <h2 id="edit-product-title">Edit product</h2>

        <app-product-form />

        <button type="button" (click)="close()">Close</button>
      </section>
    </div>
  `,
})
export class EditProductModal {
  private readonly router = inject(Router);
  private readonly route = inject(ActivatedRoute);

  close(): void {
    this.router.navigate(
      [{ outlets: { modal: null } }],
      {
        relativeTo: this.route.parent,
        queryParamsHandling: 'preserve',
        replaceUrl: true,
      },
    );
  }
}

That example demonstrates the routing relationship, not a production-complete modal. A custom modal must also:

move focus inside when it opens;
trap focus while open;
close on Escape when appropriate;
restore focus when it closes;
prevent background content from being interactive;
expose a useful accessible name;
handle scrolling correctly.

The native HTML <dialog> element or Angular CDK’s dialog and accessibility utilities can remove some of that work. A visually convincing <div class="modal"> is not automatically an accessible modal.

What about route inputs and signals?

Modern Angular can bind route state directly to component inputs with withComponentInputBinding(). That can make routed modal components pleasantly small:

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withComponentInputBinding()),
  ],
};

export class EditProductModal {
  readonly productId = input.required<string>();
}

This is especially useful for the child-path and auxiliary-route approaches because productId is a real route parameter.

For query parameters, direct input binding can also be convenient, but we still need coordination code if an imperative overlay such as MatDialog must open and close in response.

Signals improve how we consume route state; they do not change the architectural choice of where that state belongs in the URL.

A practical comparison

Approach	Example URL	Best fit	Main drawback
Query parameter	`/products?dialog=edit&productId=42`	Optional UI state attached to the current page	Coordination lives in the page
Child path	`/products/42/edit`	A modal that belongs to one parent resource or page	Parent layout and route bridge are required
Auxiliary route	`/products(modal:edit/42)`	Page and modal are independent routed regions	More unusual URL and router syntax

My default decision process is:

If the modal is temporary and should not survive refresh, do not route it.
If it is optional state of the current page, start with a query parameter.
If it is a destination naturally nested under one page, use a child path.
If it must coexist with several unrelated primary routes, consider an auxiliary route.

There is no universally “most Angular” answer. The URL should describe the product behaviour you want.

A few rules that apply to all three

Whichever option you choose:

Treat the URL as the source of truth.
Test pasted deep links, not only clicks from inside the app.
Test Back and Forward while the modal is open.
Close the overlay when its route is deactivated.
Prevent afterClosed() from overriding a navigation already in progress.
Put stable identifiers in the URL, then load the data from a service, store, or resolver.
Decide deliberately whether closing should push or replace a history entry.
Do not sacrifice modal accessibility just because routing works.
Add an SSR-safe fallback or render routed modal content declaratively if the route can be rendered on the server.

That second-to-last point deserves repeating. A modal with a beautiful URL but broken keyboard focus is still a broken modal.

Final thought

Routing a modal is not really about calling open() from the Router. It is about deciding whether the modal is part of your application’s navigable state.

Once that decision is clear, the implementation becomes much easier: choose the URL shape that tells the truth, let navigation drive the UI, and make closing the modal a navigation too.

Choosing the right RxJS Operator for Action Streams

Michele Stieven — Mon, 27 Jul 2026 05:03:03 +0000

If you use RxJS action streams (maybe for API calls?), you have probably paused over the same question I have:

Should this effect use mergeMap, switchMap, concatMap, or exhaustMap?

The honest answer is not “use this operator for GET and that operator for POST.” The right choice depends on what a repeated action means in your application.

I will use NgRx Effects in the first example because it is a familiar action-based API, but the ideas in this article are not tied to @ngrx/effects. They apply whenever an RxJS stream represents commands or events that start asynchronous work—for example, in an NgRx SignalStore method built with rxMethod, in a ComponentStore effect, or in your own action stream.

Let’s build a mental model that makes that choice much less mysterious.

The familiar effect

A typical effect listens for an action, calls a service, and maps the result to either a success or a failure action:

import { inject } from '@angular/core';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { catchError, map, of, switchMap } from 'rxjs';

export const loadTodos = createEffect(
  (
    actions$ = inject(Actions),
    todoService = inject(TodoService),
  ) =>
    actions$.pipe(
      ofType(TodosPageActions.load),
      switchMap(() =>
        todoService.getAll().pipe(
          map((todos) => TodosApiActions.loadSuccess({ todos })),
          catchError((error: unknown) =>
            of(TodosApiActions.loadFailure({ error })),
          ),
        ),
      ),
    ),
  { functional: true },
);

Modern NgRx supports functional effects, so the full example above uses one. From this point on, I will show only the relevant actions$.pipe(...) fragment. You can place the same pipeline inside a class-based effect, a functional effect, an rxMethod, or another RxJS-based action handler.

First: what are we flattening?

An action stream is an Observable. For every action, our service returns another Observable. We therefore have an Observable producing Observables—a higher-order Observable.

The four common flattening operators decide what happens when a new action arrives while the previous inner Observable is still running:

Operator	When another action arrives	Useful mental model
`mergeMap`	Subscribe to it too	Run in parallel
`concatMap`	Put it in a queue	One at a time, in order
`switchMap`	Unsubscribe from the previous inner Observable and switch to the new one	Latest subscription wins
`exhaustMap`	Ignore the new action while the current inner Observable is active	First one wins until completion

That last column is more useful than memorising a rule per HTTP verb.

`mergeMap`: run everything

mergeMap subscribes to every inner Observable as it arrives. Requests may run concurrently, and their responses may arrive in a different order.

This is a good fit when every operation matters and the operations are independent.

The danger is a race condition. If two responses update the same state, an older request can finish last and overwrite newer data.

`concatMap`: queue everything

concatMap waits for the current inner Observable to complete before subscribing to the next one.

Nothing is dropped, and the client starts operations in action order. The trade-off is waiting: one slow request blocks everything queued behind it.

This is often a good default for writes that must be applied in order.

`switchMap`: keep listening only to the latest

When a new action arrives, switchMap unsubscribes from the previous inner Observable and subscribes to the new one.

With Angular HttpClient, unsubscribing normally aborts the client-side request. But be careful with the wording: this does not prove that the server never received or processed it. A write may already have crossed that boundary.

This makes switchMap excellent for replaceable reads—search suggestions are the classic example—but risky as a general policy for writes.

`exhaustMap`: ignore repeated triggers

exhaustMap accepts the first action, then ignores new actions until the active inner Observable completes.

It is useful when repeated triggers are accidental or meaningless: double-clicking a login button, submitting the same form twice, or requesting the same deletion while it is already in progress.

Remember that ignored actions are not queued. They are gone.

Do not choose by HTTP verb alone

“Use switchMap for GET” sounds convenient, but it is too broad.

Ask these questions instead:

Does every action represent work that must happen?
Can two operations safely run at the same time?
Does order matter?
Is a newer action a replacement for an older one?
Should repeated actions be ignored while one is running?
Are those answers global, or only true for actions concerning the same entity?

The last question is where things get interesting.

Loading one replaceable collection

Suppose the store contains one visible list of todos. Every load action means “replace that list with the newest response.”

Here, switchMap is a natural fit:

actions$.pipe(
  ofType(TodosPageActions.load),
  switchMap(() =>
    todoService.getAll().pipe(
      map((todos) => TodosApiActions.loadSuccess({ todos })),
      catchError((error: unknown) =>
        of(TodosApiActions.loadFailure({ error })),
      ),
    ),
  ),
);

If the user refreshes twice, we usually care about the latest refresh, not both responses.

exhaustMap could also be correct—but it expresses a different product decision. It says that refresh clicks should be ignored until the current request completes. NgRx’s own effects guide uses this pattern in a collection-loading example. Neither operator is universally right; the UX decides.

Loading a collection with query parameters

Now imagine:

TodosPageActions.load({ completed: true });
TodosPageActions.load({ completed: false });

Should the first request be cancelled?

It depends on the state model.

If the store holds only the currently selected list, the second action replaces the first query. switchMap is still appropriate:

switchMap(({ completed }) =>
  todoService.getAll({ completed }).pipe(
    map((todos) =>
      TodosApiActions.loadSuccess({ completed, todos }),
    ),
    catchError((error: unknown) =>
      of(TodosApiActions.loadFailure({ completed, error })),
    ),
  ),
)

If the store caches a separate result for each query, both requests matter. mergeMap may be the better choice:

mergeMap(({ completed }) =>
  todoService.getAll({ completed }).pipe(
    map((todos) =>
      TodosApiActions.loadSuccess({ completed, todos }),
    ),
    catchError((error: unknown) =>
      of(TodosApiActions.loadFailure({ completed, error })),
    ),
  ),
)

Notice that the success action includes the query. Without it, the reducer may not know which cache entry to update.

The parameter alone did not determine the operator. The way we store the result did.

Loading individual entities

Consider these actions:

TodosPageActions.loadOne({ id: 1 });
TodosPageActions.loadOne({ id: 2 });

The requests concern different entities, so cancelling one because the other started would be surprising. mergeMap allows both to run:

mergeMap(({ id }) =>
  todoService.get(id).pipe(
    map((todo) => TodosApiActions.loadOneSuccess({ todo })),
    catchError((error: unknown) =>
      of(TodosApiActions.loadOneFailure({ id, error })),
    ),
  ),
)

But what about this?

TodosPageActions.loadOne({ id: 1 });
TodosPageActions.loadOne({ id: 1 });

Now the requests target the same entity. If they run in parallel, an older response could arrive last.

What we really want is:

different IDs: run in parallel;
the same ID: keep only the latest subscription.

That is keyed concurrency.

Keyed concurrency with `groupBy`

RxJS’s groupBy can split the action stream into one stream per ID. We can use switchMap inside each group and mergeMap across groups:

actions$.pipe(
  ofType(TodosPageActions.loadOne),
  groupBy(({ id }) => id),
  mergeMap((actionsForId$) =>
    actionsForId$.pipe(
      switchMap(({ id }) =>
        todoService.get(id).pipe(
          map((todo) =>
            TodosApiActions.loadOneSuccess({ todo }),
          ),
          catchError((error: unknown) =>
            of(TodosApiActions.loadOneFailure({ id, error })),
          ),
        ),
      ),
    ),
  ),
);

This gives us both behaviours:

requests for different entities can run concurrently;
a newer request for the same entity replaces the previous subscription.

If the discriminator is a query object, create a stable key from the meaningful fields. Do not casually use JSON.stringify unless key order and normalisation are under your control.

A `groupBy` lifetime warning

Application-level action streams are usually long-lived. Without a duration, every distinct group created by groupBy also remains available for the life of the subscription. That is harmless for a small, bounded set of keys, but an unbounded stream of unique IDs can retain an unbounded number of groups.

RxJS lets you provide a duration that closes an inactive group:

groupBy(
  ({ id }) => id,
  {
    duration: (group$) => group$.pipe(debounceTime(30_000)),
  },
)

This deserves more caution than it usually gets. If a group closes while one of its requests is still active, a later action with the same key creates a new group. The old request and the new group can then overlap, weakening the per-key guarantee.

Use a duration only when its timing is valid for your domain, or when that occasional overlap is acceptable. For strict, reusable keyed concurrency, prefer a thoroughly tested custom operator or a request-coordination layer with explicit lifecycle tracking. A five-second timeout copied from a blog post is not a correctness proof—I say that with affection as someone who once wanted it to be one.

Creating entities

For independent creates, every action normally matters. mergeMap lets them run concurrently:

actions$.pipe(
  ofType(TodosPageActions.add),
  mergeMap(({ draft }) =>
    todoService.add(draft).pipe(
      map((todo) => TodosApiActions.addSuccess({ todo })),
      catchError((error: unknown) =>
        of(TodosApiActions.addFailure({ draft, error })),
      ),
    ),
  ),
);

Use concatMap instead if creation order matters or the server requires serial execution.

Use exhaustMap if the UI represents a single submission and double-submission must be ignored. Disabling the submit button while the request is pending is still a good UX improvement, but the effect can provide a second line of defence.

switchMap is rarely the safe default for a create. Unsubscribing does not undo a record the server has already created.

Updating entities

This is where I would change a common recommendation: for writes to the same entity, “latest wins” on the client is not enough.

Imagine two edits:

TodosPageActions.update({ id: 1, changes: { title: 'First' } });
TodosPageActions.update({ id: 1, changes: { title: 'Second' } });

With switchMap, the first response may be ignored, but the server might still apply the first update after the second. The client then looks correct until the next reload reveals stale data.

A safer client-side policy is:

different IDs: update in parallel;
the same ID: queue updates in order.

actions$.pipe(
  ofType(TodosPageActions.update),
  groupBy(({ id }) => id),
  mergeMap((actionsForId$) =>
    actionsForId$.pipe(
      concatMap(({ id, changes }) =>
        todoService.update(id, changes).pipe(
          map((todo) =>
            TodosApiActions.updateSuccess({ todo }),
          ),
          catchError((error: unknown) =>
            of(TodosApiActions.updateFailure({ id, error })),
          ),
        ),
      ),
    ),
  ),
);

This preserves the order in which the client sends updates for each entity. It does not solve every distributed-systems problem: other clients can still write concurrently. If that matters, use server-side concurrency control such as version numbers, ETags, or conflict detection.

For high-frequency UI changes, another valid design is to debounce before sending writes, or to dispatch a “commit” action separately from local edits. That is a product and data-consistency decision, not merely an operator choice.

Deleting entities

For deletion, duplicate requests for the same ID are usually pointless, while deletions of different IDs can run in parallel.

That suggests exhaustMap per key:

actions$.pipe(
  ofType(TodosPageActions.delete),
  groupBy(({ id }) => id),
  mergeMap((actionsForId$) =>
    actionsForId$.pipe(
      exhaustMap(({ id }) =>
        todoService.delete(id).pipe(
          map(() =>
            TodosApiActions.deleteSuccess({ id }),
          ),
          catchError((error: unknown) =>
            of(TodosApiActions.deleteFailure({ id, error })),
          ),
        ),
      ),
    ),
  ),
);

A global exhaustMap would also suppress deletion of ID 2 while ID 1 is being deleted. That may be right for a single confirmation dialog, but it is too restrictive for many list UIs.

Also consider making deletion idempotent on the server. Client-side operator choices help the UX; server-side semantics protect the system.

A practical decision table

These are starting points, not laws:

Situation	Likely choice	Why
Latest search or filter replaces the previous one	`switchMap`	Old results are no longer useful
Refresh clicks should be ignored while loading	`exhaustMap`	Prevent duplicate in-flight loads
Independent reads or creates	`mergeMap`	All operations matter and may run together
Ordered writes	`concatMap`	Preserve client-side execution order
Latest read per entity	`groupBy` + `switchMap`	Replace only requests with the same key
Ordered writes per entity	`groupBy` + `concatMap`	Serialize the same entity, parallelise different ones
Ignore duplicate work per entity	`groupBy` + `exhaustMap`	Suppress repeats only for the same key

When uncertain, describe the desired behaviour in plain English first:

Run all of them, queue them, replace the previous one, or ignore the new one?

Then decide whether that rule applies to the whole action stream or separately per entity.

Should we hide this in a custom operator?

A custom operator can remove repetition, but it also hides the most important behaviour in the effect: concurrency.

Names such as PARALLEL, QUEUE, LATEST, and IGNORE_WHILE_BUSY are readable, but a general helper must also get error handling, typing, key lifetimes, cancellation, and per-key cleanup right. That is quite a contract.

My current preference is:

keep the standard RxJS operator visible for simple effects;
extract a keyed operator only after the pattern repeats;
give it a behavioural name;
test it with marble tests, including same-key and different-key actions;
document exactly what happens when groups expire and requests outlive them.

Abstraction should make the concurrency policy clearer, not merely make the pipe shorter.

Final thought

The best flattening operator is not determined by GET, POST, PATCH, or DELETE, nor by whether you happen to be using NgRx Effects, SignalStore, or a home-grown action stream. It is determined by which actions matter, which may overlap, and what your state considers “the same piece of work.”

Once you ask those questions, the four operators stop feeling like RxJS trivia and start looking like four very precise product decisions. And that is much easier to reason about.

Recreating LinkedIn’s Crossclimb Game with Angular - Part 3

Michele Stieven — Fri, 14 Nov 2025 01:34:41 +0000

Now that we've taken care of the game's logic with a service, it's time to end our little project with a couple more components!

The `Hint` component

But first, let's create a simple component to display the current hint to the user: create the file /components/hint.ts.

import { Component } from '@angular/core';

@Component({
  selector: 'app-hint',
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      background: rgba(0,0,0,.1);
      color: grey;
      display: block;
      position: absolute;
      bottom: 0;
      left: 0;
      right: 0;
      height: 2rem;
      padding: 2em;
      text-align: center;
    }
  `
})
export class Hint {}

This component does nothing more than styling: it'll place our hint on the bottom of the page via Content Projection, like this:

<app-hint>This is a hint</app-hint>

The Container

Time for our final component: the GameContainer! This one will be in charge of displaying all the words, binding the states from our service, and listening to events. Essentially, it is the main orchestrator of our game. Create the file components/game-container.ts.

@Component({
  selector: 'app-game-container',
  template: `
    @if (gameService.game(); as game) {
      <div class="game-container">

      </div>
    }

    <app-hint>{{ gameService.currentHint() }}</app-hint>
  `,
  imports: [Hint],
  styles: `

  `
})
export class GameContainer {

  gameService = inject(GameService);

  ngOnInit() {
    this.gameService.init();
  }
}

For now, all it does is to display the current hint to the user, and it also sets up a container <div>. It is also responsible for initializing the game.

Just put it in your main component, like this:

@Component({
  selector: 'app-root',
  template: `
    <app-game-container />
  `,
  imports: [GameContainer],
})
export class App {}

Now go back to the GameContainer component: let's add some template.

From now on, we'll be working inside the <div class="game-container"> element.

Showing the edge words

First, we'll show the top word.

<app-word
  [letters]="game.currentEdgeWords[0].split('')"
  [isReadonly]="gameService.gameStatus() !== 'sorted' || gameService.gameStatus() === 'solved'"
  [isFinal]="true"
  [isLocked]="gameService.gameStatus() === 'error' || gameService.gameStatus() === 'unsorted'"
  (lettersChange)="onLettersChange(0, $event)"
  (lastKeydown)="focusWord(game.words.length + 1)"
/>

This is what we're doing:

We're binding the current top word (transforming it from an array to a single string).
We're binding isReadonly, isFinal and isLocked with the appropriate expressions.

Don't forget to import the Word component!

We're also listening to two events: lettersChange and lastKeydown. The first one is responsible for updating the state, the second one is needed to jump to the bottom word when the user has entered the last letter (for convenience). So, we need to create two metods.

The first one is really simple, all it has to do is to call the methods we've already created in our service:

onLettersChange(wordIndex: number, letters: string[]) {
  if (wordIndex === 0) {
    this.gameService.replaceTop(letters.join(''));
  } else if (wordIndex === this.gameService.game()!.words.length + 1) {
    this.gameService.replaceBottom(letters.join(''));
  } else {
    this.gameService.replaceWord(wordIndex - 1, letters.join(''));
  }
}

The wordIndex we get goes from 0 to 6, so we're calling the appropriate method based on that.

Then, we need the ability to focus on some element in our view. To do that, we need to use viewChildren:

  wordComponents = viewChildren(Word);

Import it from @angular/core.

This is a Signal which contains all the Word components on this page. Now we can create the focusWord() handler:

focusWord(i: number) {
  this.wordComponents()[i]?.focus(0);
}

Perfect! Now for the bottom word, things are mostly the same, except that we're binding to the second edge word, and we don't need to listen to the lastKeydown event:

<app-word
  [letters]="game.currentEdgeWords[1].split('')"
  [isReadonly]="gameService.gameStatus() !== 'sorted' || gameService.gameStatus() === 'solved'"
  [isFinal]="true"
  [isLocked]="gameService.gameStatus() === 'error' || gameService.gameStatus() === 'unsorted'"
  (lettersChange)="onLettersChange(game.words.length + 1, $event)"
/>

You should now see both words, in a locked state:

The middle words

It's time to display the middle words! In order to have the drag & drop functionality, we need the Angular CDK, so install it like this:

npm install @angular/cdk

Now, between the two words, put this template:

<div cdkDropList class="sortable-list" (cdkDropListDropped)="drop($event)">
  @for (word of game.words; track i; let i = $index) {
    <div cdkDrag class="word-container">

    </div>
  }
</div>

Here we're displaying all of our middle words. But also:

We're using the cdkDropList directive to tell Angular that this is where we'll put our draggable elements.
We're using the cdkDrag directive to the elements that we want to drag.
We're listening to the cdkDropListDropped event which tells us when an element has been dropped.

So, first of all, import the directives:

import { CdkDropList, CdkDrag } from '@angular/cdk'; 

// ...
  imports: [Word, CdkDropList, CdkDrag, Hint, Icon],

Then, we need to implement the drop() handler. This is how it looks like:

  drop(event: CdkDragDrop<string[]>) {
    const words = [...this.gameService.game()!.words];
    moveItemInArray(words, event.previousIndex, event.currentIndex);
    this.gameService.game.update(game => ({ ...game!, words }));
  }

Import CdkDragDrop and moveItemInArray from @angular/cdk and place them in the imports array.

Here we're cloning the original array of words (we don't want to mutate it) and sorting it with the helper moveItemInArray from the CDK. Then, we're updating the state with the ordered words.

Believe it or not, the class is done! All we need to do now is to add some more elements and some styles.

Place your cursor inside the <div cdkDrag class="word-container"> element and add the following:

<app-word
  [letters]="word.current.split('')"
  [isReadonly]="gameService.gameStatus() !== 'error'"
  (focusedChange)="gameService.focused.set($event !== null ? i : null)"
  (lettersChange)="onLettersChange(i + 1, $event)"
  (lastKeydown)="$last ? '' : focusWord(i + 2)"
/>

This is more or less the same thing we did for the edge words, but:

The bindings and conditions are different.
We're using i + 1 on the lettersChange event because we need to account for the top word.
We're using i + 2 on lastKeydown for the same reason.

Also, we're listening to focusedChange to know when the user has focused this word. For our state, we don't actually need to know the index of the character (the $event), just the index of the word.

One more touch: we don't want the user to drag the words normally, we want to make sure they drag an icon, so let's add two icons, one per side! Place this immediately after the previous template.

<div cdkDragHandle [style.display]="gameService.gameStatus() !== 'sorted' && gameService.gameStatus() !== 'solved' ? 'block' : 'none'">
  <app-icon icon="bars" />
</div>

<div cdkDragHandle [style.display]="gameService.gameStatus() !== 'sorted' && gameService.gameStatus() !== 'solved' ? 'block' : 'none'">
  <app-icon icon="bars" />
</div>

Import CdkDragHandle from @angular/cdk and place it in the imports array.

All that's left to do is some styling! Put these styles in your component:

These are some simple styles to make it functional, feel free to tweak them!

.game-container {
  max-width: 400px;
  padding: 2em;
  margin: 0 auto;
}
.word-container {
  position: relative;
}
[cdkDragHandle] {
  position: absolute;
  top: 50%;
  display: block;
  cursor: pointer;
}
[cdkDragHandle]:nth-of-type(1) {
  left: 0;
  transform: translate(-50%, -50%);
}
[cdkDragHandle]:nth-of-type(2) {
  right: 0;
  transform: translate(50%, -50%);
}
.sortable-list {
  border: 2px solid rgba(0,0,0,.05);
  border-top: none;
  border-bottom: none;
 }
app-word {
  display: block;
  padding: 10px 30px;
}
.cdk-drag-placeholder {
  opacity: 0;
}
.cdk-drag {
  overflow: visible;
}
.cdk-drag-animating {
  transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);
}
.sortable-list.cdk-drop-list-dragging > *:not(.cdk-drag-placeholder) {
  transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);
}

All the classes with the cdk- prefix are automatically applied by the CDK, we just need to style them. The CDK actually clones the element when it moves, so we're just making the previous one invisible while we drag.

And we're done! Our game is now complete! [Link to the final code]

Where to go from here

The game is fully working, but the original one has a couple more features. Feel free to implement them as an exercise! For example:

Request the GameInfo object from an actual server.
Start a timer as soon as the game is loaded, and stop it when the puzzle is solved. You could do it easily with RxJS.
Display a button which reveals the focused word.
Display a button which reveals only one missing letter of the focused word.
Finally, to make it more challenging, allow the user to click on these buttons only every 10 seconds or so. Again, this should be pretty easy with RxJS!

I hope this has been a fun little project to build, as it was for me! Hope you liked it!

Recreating LinkedIn’s Crossclimb Game with Angular - Part 2

Michele Stieven — Thu, 13 Nov 2025 00:29:30 +0000

In the previous article we wrote the main component for our app: the Word component. Now, it's time to implement some game logic!

The models

Create a models/game.ts file which will store our models.

First, we have a GameInfo interface: this is what could be eventually be store on a server (we won't have one, but we'll pretend that we do). It stores the 5 middle words, each with its own hint, the 2 edge words (top and bottom) and a common hint.

/** What comes from the server */
export interface GameInfo {
  words: Array<{ correct: string; hint: string }>;
  edgeWords: [string, string];
  edgeHint: string;
};

Then, we need a similar interface, which I called Game, which stores some additional strings: the user's current values.

/** What we store in our component */
export interface Game {
  words: Array<{ correct: string; hint: string; current: string }>;
  edgeWords: [string, string];
  currentEdgeWords: [string, string];
  edgeHint: string;
};

This is what I imagined for the purpose of this demo, but it's not the only way to store the data.

As I said, we won't use an actual server, so let's export some fake data!

export const mock: GameInfo = {
  words: [
    { correct: 'CARE', hint: 'Compassionate attention given to someone' },
    { correct: 'CORE', hint: 'Discarded part of an apple' },
    { correct: 'CORK', hint: 'Stopper in a champagne bottle' },
    { correct: 'FORK', hint: 'Eating utensil with tines' },
    { correct: 'FORT', hint: '____nite (popular online game)' }
  ],
  edgeWords: ['BARE', 'FOOT'],
  edgeHint: 'Compound word for "having no shoes or socks on"'
};

Remember that the 2 edge words share a common hint!

So, to recap, the user will have to guess these words in this exact order:

BARE
CARE
CORE
CORK
FORK
FORT
FOOT

The service

We'll store pretty much all of our data in a service, so create a services/game.service.ts file.

This is where you may use a State Management solution, like NgRx. We'll keep it simple and use Angular Signals!

@Injectable({ providedIn: 'root' })
export class GameService {

}

This service will hold 2 states: game and focused.

@Injectable({ providedIn: 'root' })
export class GameService {

  game = signal<Game | null>(null);
  focused = signal<number | null>(null);
}

game will store the current Game object, and focused will store the index of the focused word (in our case, since we have 7 words, 0 to 6). We'll take advantage of this state to show the appropriate hint to the user.

Let's implement a method to initialize the game object. In a real scenario, you would perform an HTTP request, but we'll use our mock data!

  init() {
    const emptyString = Array(mock.edgeWords[0].length).fill(' ').join('');
    this.game.set({
      ...mock,
      words: mock.words.map(word => ({ ...word, current: emptyString })).sort(() => Math.random() - 0.5),
      currentEdgeWords: [emptyString, emptyString]
    });
  }

Here we're simply populating the current words with empty strings. So, if our words have 4 letters, the current words will be 4 empty characters each.

We're also randomizing the order of our words (see that Math.random()?), so that the user will be forced to sort them correctly!

The derived states

All of the info we need can be derived from our game and focused states, so let's create some derived states using computed.

First, let's calculate the word length, just for convenience.

  wordLength = computed(() => this.game()?.edgeWords[0].length || 0);

It doesn't matter which word you choose, they have the same length.

We also need to know the current game status. The game could be in 5 different states:

idle (game not loaded yet)
error (not solved at all)
unsorted (middle words are solved, but not sorted)
sorted (middle words have been sorted)
solved (the edge words have been solved)

In order to calculate it, we need a helper method: let's call it differByOne(), and its job will be to tell us if 2 strings differ by exactly one character.

  private differByOne(str1: string, str2: string) {
    if (str1.length !== str2.length) return false;

    let diffCount = 0;

    for (let i = 0; i < str1.length; i++) {
      if (str1[i] !== str2[i]) diffCount++;
      if (diffCount > 1) return false;
    }

    return diffCount === 1;
  }

Now we can write our gameStatus derived state!

  gameStatus = computed(() => {

  });

First, we check if there is a game at all. If we have no game, we return idle.

    const game = this.game();
    if (!game) return 'idle';

Then, we check if the middle words have been solved, and if not, we return error.

    const isHalfSolved = game.words.every(word => word.correct === word.current);

    if (!isHalfSolved) return 'error';

Then, we check if the middle words have been sorted correctly, and if not, we return unsorted.

    const isSorted =
      isHalfSolved
      && game.words.every((word, i) => i === game.words.length - 1 || this.differByOne(word.current, game.words[i + 1].current))

    if (!isSorted) return 'unsorted';

The words could be arranged in reverse order, it doesn't matter.

Finally, we check if the edge words are correct (and we check that the top one and the first middle word differ by one character, to make sure they're written in the correct order).

    const isSolved =
      isHalfSolved
      && isSorted
      && game.currentEdgeWords.every((word, i) => game.edgeWords.includes(word))
      && this.differByOne(game.currentEdgeWords[0], game.words[0].current);

    if (!isSolved) return 'sorted';
    return 'solved';

This derived state is done!

We just need another one: we'll call it currentHint, and it will store the hint to show to the user based on the gameStatus and the focused index.

currentHint = computed(() => {
    if (this.gameStatus() === 'solved') return 'Solved!';
    if (this.gameStatus() === 'sorted') return 'Top + bottom: ' + this.game()!.edgeHint;
    if (this.gameStatus() === 'unsorted') return 'Sort the rows!';
    if (this.focused() === null) return undefined;

    return this.game()?.words.at(this.focused()!)!.hint;
  });

This should be self-explanatory.

We're almost done with our service! We just need 3 additional methods to mutate our game state.

First, create a replaceWord method to change the value of one of the middle words:

  replaceWord(index: number, text: string) {
    this.game.update(game => (game && {
      ...game,
      words: game.words.map((word, i) => {
        if (index !== i) return word;
        return { ...word, current: text }
      })
    }))
  }

The index will go from 0 to 4 since we're only dealing with the 5 middle words.

Then, two similar methods to replace the edge words:

  replaceTop(word: string) {
    this.game.update(game => (game && {
      ...game,
      currentEdgeWords: [word, game.currentEdgeWords[1]] 
    }));
  }

  replaceBottom(word: string) {
    this.game.update(game => (game && {
      ...game,
      currentEdgeWords: [game.currentEdgeWords[0], word]
    }));
  }

And we're done! In the next article we'll take advantage of our Word component and our newly created GameService to display the actual game, with the help of the Angular CDK.

At the end, we'll have something like this:

Recreating LinkedIn’s Crossclimb Game with Angular - Part 1

Michele Stieven — Wed, 12 Nov 2025 01:45:38 +0000

In this short series, we’ll use Angular to recreate the popular LinkedIn game Crossclimb, a fun word puzzle that’s perfect for showing off the power of Signals in modern Angular.

This project is not only a great coding exercise, but also an enjoyable way to explore reactive state management using Signals.
So, fire up your terminal, create a new Angular app, and let’s build together! 🚀

How the game works

If you’ve never played Crossclimb before, here’s a quick rundown:

The goal is to guess seven words using a set of hints to form a connected word chain. Each consecutive pair of words differs by exactly one character, for example, “code” → “cove” → “love”.

You’ll start by completing and correctly arranging the five middle words. Once that’s done, the first and last words unlock. They come with a hint to help you guess them, and they’re connected by a logical relationship.

When all seven words are correctly guessed, you’ve solved the puzzle! 🎉

The `Word` component

Feel free to use your favorite font for the project: for my demo, I've used Roboto, so I wrote this in my global styles:

@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap');

body, * {
  font-family: "Roboto", sans-serif;
  font-optical-sizing: auto;
  font-style: normal;
  font-variation-settings: "wdth" 100;
}

First, create the main component, called Word, in a file (eg. /components/word.ts):

import { Component } from "@angular/core";

@Component({
  selector: 'app-word',
  imports: [],
  template: `
  `,
  styles: ``
})
export class Word {

}

On the surface, this component is pretty simple: it's a box containing multiple <input> elements in a row (one for each letter).

However, there are some behaviors we need to implement, for example:

Each <input> must contain a single letter (or none)
If the user writes a second letter, it must replace the previous one
After the user enters a letter, we must automatically focus the next <input>, so that the user can type the whole word easily
We must display a bottom border where if there is no letter, to indicate that it's missing

This is an example of how we'll use this component:

<app-word
  [letters]="[' ', ' ', ' ', ' ']"
  [isReadonly]="false"
  [isFinal]="false"
  [isLocked]="false"
  (lettersChange)="..."
  (focusedChange)="..."
  (lastKeydown)="..."
/>

So, we need 4 inputs:

letters will be an array of characters (empty character for a missing letter)
isReadonly will stop the user from changing the letters (we'll set it to true once the user is done with the middle words)
isFinal will be used for the first and last words (just to style them with a different color)
isLocked will display a lock icon on top of the word (just for the first and last words, initially)

And two outputs:

lettersChange will give us back a new array of letters when the user changes one of them
focusedChange will tell us the index of the character which is currently focused by the user, we need this in order to display the correct hint. We don't actually need the index (we just need to know which word it is) but it may come in handy.
lastKeydown will be emitted when the user has typed something on the last <input>, we'll use this to focus on the next word automatically.

Let's write them, starting with the inputs.

export class Word {

  isReadonly = input(false);
  isFinal = input(false);
  isLocked = input(false);
  letters = model.required<string[]>();
  focused = model<number | null>(null);
}

letters and focused are actually models, a particular type of input which can also be overridden by the component itself. Also, each model automatically creates an output with the same name but with the Change suffix: this means we get lettersChange and focusedChange for free! They'll emit the new value once the model value changes.

Then, create the missing output:

  lastKeydown = output();

The template

It's time to display something! This will be the template for our component:

<div class="container" [class.final]="isFinal()">
  @for (_ of [].constructor(letters().length); let i = $index; track i) {
    @let letter = letters()[i];
    <input
      #input
      type="text"
      [class.with-border]="letter === ' ' && !isReadonly() && !isLocked()"
      [class.highlighted]="focused() === i && !isReadonly() && !isLocked()"
      [value]="letter === ' ' ? '' : letter"
      [readonly]="isReadonly()"
      (keydown)="onKeydown(i, $event)"
      (focus)="focused.set(i)"
      (blur)="focused.set(null)"
    >
  }
  @if (isLocked()) {
    <div class="overlay">
      <!--<app-icon icon="lock" />-->
    </div>
  }
</div>

Here's what's going on...

The whole template is wrapped inside a .container element, with an optional class final which will simply change its background color.
We're creating an empty array with a trick ([].constructor(letters().length)) to be able to use @for to display the correct number of <input>s.
We're extracting each letter inside a template variable (@let letter).
We're using a reference variable #input to be able to grab the elements later.
We're applying some dynamic classes on the elements, just for styling.
We're binding properties and listening to events to change our states.
We're adding an overlay to display a lock icon on top of the element while the component is still locked (initially, the first and last word).

There are a few things missing: the keydown event handler, an <app-icon> component, and some styling.

First, let's create an empty handler just to make it work:

  onKeydown(index: number, e: KeyboardEvent) {}

Then, apply some styling to our component. Feel free to use these styles:

  .container {
    position: relative;
    display: flex;
    justify-content: space-evenly;
    background: lightgrey;
    border-bottom: 2px solid grey;
    border-radius: 4px;
    padding: 10px;
  }
  input {
    border: none;
    background: transparent;
    width: 1.5em;
    text-align: center;
    outline: none;
    padding: 0;
    font-weight: bold;
  }
  .with-border {
    border-bottom: 2px solid grey;
  }
  .highlighted {
    border-bottom: 2px solid black;
  }
  .final {
    background: #FFCBA4;
  }
  .overlay {
    position: absolute;
    inset: 0;
    background: transparent;
    align-items: center;
    justify-content: center;
    display: flex;
  }

Feel free to test this component! Just place it in your app:

@Component({
  selector: 'app-root',
  template: `
    <app-word [letters]="[' ', ' ', ' ', ' ']" />
  `,
  imports: [Word]
})
export class App {
}

And you should see something like this:

We just need to apply the correct logic when the user enters a letter: let's do it!

Handling the `keydown` event

We'll need the ability to focus on a specific <input>, and in order to do that we must grab a reference to them!

We've already applied an #input reference variable on our template, so we're able to grab all our <input> elements with the help of viewChildren:

import { ..., viewChildren } from "@angular/core";

// ...

  // Inside the component's class
  inputs = viewChildren<ElementRef<HTMLInputElement>>('input');

This will give us a Signal which contains an array of ElementRefs, with all of our native elements inside.

Create a focus method that you'll use to focus on the correct element:

  focus(index: number) {
    this.inputs()[index]?.nativeElement.focus();
  }

Now, it's time to implement the onKeydown() method! So position your cursor inside of it and write the following code... Feel free to test each step on your own!

First, if the word is readonly, we must do nothing and stop the event, so that nothing is written inside our element:

  if (this.isReadonly()) {
    e.preventDefault();
    return;
  }

If the user takes advantage of the tab key to navigate the <input>s, allow it (don't prevent the event), but do nothing on the element.

  if(e.key === 'Tab') {
    return;
  }

Then, the user could delete a character by using backspace or delete. We'll also add a simple check, so that if backspace is used on an empty character, we'll focus the previous <input>, to make it easier for the user.

  if (e.key === 'Backspace' || e.key === 'Delete') {
    if (e.key === 'Backspace' && this.letters()[index] === ' ') {
      this.focus(index - 1);
    }
    this.letters.update(letters => letters.map((l, i) => index !== i ? l : ' '));
  }

At this point, stop the event so that nothing is written inside the input. We'll add the character ourself in our state, and Angular will automatically replace in on the DOM thanks to our [value] binding!

  e.preventDefault();

Finally, we need to mutate our state with the new letter:

  if (isLetter && letter !== previousLetter) {
    this.letters.update(letters => letters.map((l, i) => index !== i ? l : letter));
    if (index === this.letters().length - 1) {
      this.lastKeydown.emit();
    } else {
      this.focus(index + 1);
    }
  }

Notice that we're also focusing on the next <input>, and if there is none, we're just emitting the lastKeydown event. We'll use it later in another component!

Our main component is done! Feel free to test it out!

Here's the entire onKeydown() method:

  onKeydown(index: number, e: KeyboardEvent) {
    if (this.isReadonly()) {
      e.preventDefault();
      return;
    }
    if(e.key === 'Tab') {
      return;
    }
    if (e.key === 'Backspace' || e.key === 'Delete') {
      if (e.key === 'Backspace' && this.letters()[index] === ' ') {
        this.focus(index - 1);
      }
      this.letters.update(letters => letters.map((l, i) => index !== i ? l : ' '));
    }

    e.preventDefault();

    const isLetter = /^[a-zA-Z]$/.test(e.key);
    const letter = e.key.toUpperCase();
    const previousLetter = this.letters().at(index)!.toUpperCase();

    if (isLetter && letter !== previousLetter) {
      this.letters.update(letters => letters.map((l, i) => index !== i ? l : letter));
      if (index === this.letters().length - 1) {
        this.lastKeydown.emit();
      } else {
        this.focus(index + 1);
      }
    }
  }

And this is what you should see:

The `Icon` component

We need an Icon component to display a couple of icons: one with a lock, and one with some bars (for the drag & drop functionality which we'll implement later). For the purpose of this exercise, you can just use the SVGs from Font Awesome, like this:

import { Component, input } from "@angular/core";

@Component({
  selector: 'app-icon',
  template: `
    @if (icon() === 'lock') {
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--!Font Awesome Free v7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.--><path d="M128 96l0 64 128 0 0-64c0-35.3-28.7-64-64-64s-64 28.7-64 64zM64 160l0-64C64 25.3 121.3-32 192-32S320 25.3 320 96l0 64c35.3 0 64 28.7 64 64l0 224c0 35.3-28.7 64-64 64L64 512c-35.3 0-64-28.7-64-64L0 224c0-35.3 28.7-64 64-64z"/></svg>

    } @else {
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--!Font Awesome Free v7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.--><path d="M0 96C0 78.3 14.3 64 32 64l384 0c17.7 0 32 14.3 32 32s-14.3 32-32 32L32 128C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32l384 0c17.7 0 32 14.3 32 32s-14.3 32-32 32L32 288c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32L32 448c-17.7 0-32-14.3-32-32s14.3-32 32-32l384 0c17.7 0 32 14.3 32 32z"/></svg>
    }
  `,
  styles: `
    svg {
      height: 1rem;
    }
  `
})
export class Icon {

  icon = input.required<'lock' | 'bars'>();
}

Now, just remove the comment from the Word component template, and add Icon to the imports array:

import { Icon } from "./icon";

@Component({
  selector: 'app-word',
  imports: [Icon], // Add this
  template: `

    <!-- Change this: --->
    <!--<app-icon icon="lock" />-->

    <!-- To this: -->
    <app-icon icon="lock" />
  `,
  ...
})

Try it out! Set isLocked to true and you should see something like this:

<app-word [letters]="[' ', ' ', ' ', ' ']" [isLocked]="true" />

Next steps

In the next articles of this series we'll implement the game logic and a drag & drop list using the Angular CDK. Stay tuned!

Angular Authentication with Cookies in 10 minutes

Michele Stieven — Tue, 04 Nov 2025 03:27:18 +0000

Hi folks! Long time no see!
In this short article, I’ll show you just how simple Cookie Authentication can be in Angular, all in five easy steps!

Personally, I find Cookies to be the ideal choice for most applications. They keep the front-end clean and transparent, while leaving the heavy lifting where it belongs: on the server. That said, this isn’t always the best fit for every scenario. Depending on your needs, you might opt for a hybrid setup, a fully token-based approach (like JWTs), or even OAuth 2.0 with OIDC.

If you want to dive deeper, my short e-book covers everything in detail, complete with Angular examples and mock back-ends for hands-on learning. Feel free to check it out!

AccademiaDev: text-based web development courses!

I believe in providing concise, valuable content without the unnecessary length and filler found in traditional books. Drawing from my years as a consultant and trainer, these resources—designed as interactive, online courses—deliver practical insights through text, code snippets, and quizzes, providing an efficient and engaging learning experience.

Before we begin: the server

I've already created a back-end for educational purposes: you'll find it here.

Download the code (or clone the repo)
Open a terminal
Position yourself inside the project with cd
Install the dependencies with npm install
Run the back-end with npm run dev

If all goes well, by visiting http://localhost:3000 on your browser you should see a message. We're good to go!

The server assumes that your front-end will be on localhost:4200, if it's not the case, create an .env file inside the project and set FRONTEND_URL to the full URL of your front-end. This is for CORS purposes.

Step 1: Getting the CSRF Token

A CSRF Token is a special value generated by the server (as a cookie) and stored on the browser which prevents any kind of CSRF vulnerability (eg. cross-origin same-site requests, login CSRF). It must be sent to the server (as a header) with each mutating request: this will be done automatically by Angular.

As soon as the app starts, we must get the CSRF token from the server. Let's use provideAppInitializer for that.

import { PLATFORM_ID } from '@angular/core';
import { isPlatformServer } from '@angular/common'; 
// ...

bootstrapApplication(App, {
  providers: [
    provideAppInitializer(() => {
      const http = inject(HttpClient);
      const platformId = inject(PLATFORM_ID);

        // Skip on the server (when using SSR), otherwise the request will be
        // cached and not repeated on the client-side, thus not grabbing the token.
        if (isPlatformServer(platformId)) return Promise.resolve();
        return firstValueFrom(http.get(`${env.apiUrl}/csrf-token`)
    }),
    provideHttpClient(),
  ],
});

Angular automatically saves this token and sends it with every request: as long as the Cookie name is XSRF-TOKEN, Angular will save it, and it will send it as a Header with the name X-XSRF-TOKEN for every request.

Should your server use different names, you can override them:

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'YOUR-COOKIE-NAME',
        headerName: 'YOUR-HEADER-NAME',
      }),
    ),
  ]
};

Warning: Angular doesn't send this to absolute URLs. For this reason, when working on localhost, I suggest using an URL like this: //localhost:3000. This bypasses Angular's rules, likely due to a bug, but it's useful for development.

Step 2: Sending the Cookie in `localhost`

The beautiful thing about cookies is that they are automatically sent to the server, but only to the server which created them, and only if it's on the same domain. However, during development, our server will be on a different domain (due to having a different port). For this, let's just create a simple interceptor to send them manually:

export const apiInterceptor: HttpInterceptorFn = (
  req: HttpRequest<any>,
  next: HttpHandlerFn
) => {
  // Include the `apiUrl` in your environment, like `//localhost:3000`
  if (req.url.includes(environment.apiUrl)) {
    req = req.clone({ withCredentials: true });
  }
  return next(req);
}

And provide it:

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withInterceptors([apiInterceptor])
    ),
    // ...
  ]
};

Step 3: Creating a service

Create a service to communicate with the server and store the user's data.

// For the sake of the exercise
type User = any;

@Injectable({ providedIn: 'root' })
export class AuthService {

  http = inject(HttpClient);
  router = inject(Router);

  user = signal<User | null>(null);
}

We need fetchUser method to fetch the user's data:

  /**
   * Gets the User's info from server and populates the state.
   * This is _the_ way to check if the user is still logged in.
   * If we already have it, skip the call.
   */
  fetchUser(forceReload = false): Observable<User> {
    const user = this.user();

    if (!!user && !forceReload) return of(user);

    return this.http.get<any>(`${env.apiUrl}/me`, {}).pipe(
      tap(u => this.user.set(u))
    );
  }

Then we need register and a login methods:

  register(credentials: {
    email: string,
    password: string,
    name: string,
    surname: string
  }) {
    return this.http.post<boolean>(`${env.apiUrl}/register`, credentials);
  }

  login(email: string, password: string) {
    return this.http.post<any>(`${env.apiUrl}/login`, { email, password }).pipe(
      switchMap(() => this.fetchUser()),
    );
  }

Finally, a logout method:

  logout() {
    this.http.get<any>(`${env.apiUrl}/logout`).subscribe(() => {
      this.user.set(null);
      this.router.navigateByUrl('/login');
    });
  }

Believe it or not, we're almost done!

Step 4: Detect an expired cookie

As soon as we get a 401 request, it means that we're no longer authenticated and we should be redirected to the login page. Let's create another interceptor. This is just an example, feel free to tweak it!

export const authInterceptor: HttpInterceptorFn = (
  req: HttpRequest<any>,
  next: HttpHandlerFn
) => {
  const authService = inject(AuthService);

  return next(req).pipe(
    tap({
      error: error => {
        if (error instanceof HttpErrorResponse && error.status === 401) {
          // Clears the cookies and redirects to login
          authService.logout();
        }
      }
    })
  );
}

And provide it:

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withInterceptors([apiInterceptor, authInterceptor])
    ),
    // ...
  ]
};

Step 5: Guard your pages!

Let's create a guard to check if the user is authenticated, and if not, redirect to the login page:

export const authGuard = () => {
  const authService = inject(AuthService);
  const router = inject(Router);

  return authService.fetchUser().pipe(
    map(() => true),
    catchError(() => {
      router.navigateByUrl('/login')
      return [false];
    });
  )
}

And apply it to the pages you want to protect, just make sure not to use it on the login and register pages!

export const routes: Routes = [
  {
    path: '',
    pathMatch: 'full',
    loadChildren: () => import('./pages/home/home.routes'),
    canMatch: [authGuard]
  },
  // ...
]

Use it!

We're done! Just create some pages to accomodate a login and a register form, and show the user's info!

You must register like this:

this.authService.register(credentials).subscribe(() => {
  this.router.navigateByUrl('/login');
})

You login like this:

this.authService.login(email, password).subscribe(() => {
  this.router.navigateByUrl('/');
})

Bonus: SSR Quirks

If you don't use SSR (server-side rendering), you can stop here. But if you do, there are some quirks to be aware of.

We already made sure to skip the CSRF Token call on the server, that is because if we did make that request, Angular would cache it and wouldn't repeat it on the client: we don't want that.

There's one more thing we must take care of with SSR: forwarding the Cookies.

In a normal app with client-side rendering, all API requests start from the user's browser where the cookies are stored: as a result, they're always sent automatically by the browser.

With SSR though, requests could start from the server, without the user's cookies. This means that each request which requires authentication (eg. /me to get the user profile) will fail on the server. As a result, the server will render the page as if you were not authenticated (eg. showing login buttons, redirecting to the login page if there's an auth guard…), then the client-side app will take over and modify the HTML: that's a terrible user experience.

Angular does not forward the cookies for us. In order to fix this, we must grab the user's cookies from the initial NodeJS Express Request and attach them to every request manually.

First, you need to provide the Express Request object to Angular (and while we're at it, let's pass the Response, too). In order to do so, create some InjectionTokens and provide them when the app is rendered.

Put these in a file, let's call it express-tokens.ts:

import { InjectionToken } from "@angular/core";
import { Request, Response } from "express";

export const REQUEST = new InjectionToken<Request>('Express REQUEST');
export const RESPONSE = new InjectionToken<Response>('Express RESPONSE');

Provide them in server.ts:

    commonEngine
      .render({
        bootstrap,
        documentFilePath: indexHtml,
        url: `${protocol}://${headers.host}${originalUrl}`,
        publicPath: browserDistFolder,
        providers: [
          { provide: APP_BASE_HREF, useValue: baseUrl },
          // Add these lines
          { provide: REQUEST, useValue: req },
          { provide: RESPONSE, useValue: res }
        ],
      })
      .then((html) => res.send(html))
      .catch((err) => next(err));

Then, use this interceptor to retrieve the cookies from the Request object and add them as headers:

import { isPlatformServer } from '@angular/common';
import { HttpHandlerFn, HttpHeaders, HttpRequest } from '@angular/common/http';
import { PLATFORM_ID, inject } from '@angular/core';
import { REQUEST } from '../../express-tokens';

export function cookieInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn
) {
  const location = inject(PLATFORM_ID);
  const serverRequest = inject(REQUEST, { optional: true });

  if (isPlatformServer(location)) {
    let headers = new HttpHeaders();
    const cookies = serverRequest?.headers.cookie;
    headers = headers.set('cookie', cookies ?? '');

    const cookiedRequest = req.clone({
      headers,
    });

    return next(cookiedRequest);
  }
  return next(req);
}

You'll get an error though, something among the lines of "Refused to set unsafe header 'cookie'": that's because using "cookie" as a header name is forbidden by the spec. In order for this to work, we have to disable this error with a little hack inside server.ts:

// @ts-ignore
import * as xhr2 from 'xhr2';

// HACK - enables setting cookie header
xhr2.prototype._restrictedHeaders.cookie = false;

Done!

If you're providing the HttpClient with the withFetch() configuration, this unfortunately won't work. Follow this open issue for more info.

Angular LAB: Preserving Component State Across Route Transitions

Michele Stieven — Tue, 21 Jan 2025 02:15:57 +0000

Let’s dive into a fun new exercise!

Imagine you have an application with two routes:

One displays a list of users.
The other shows details for a specific user.

You can navigate between these routes by clicking links, and you can also switch between user details using "Previous" and "Next" buttons.

Here’s an example of what it might look like:

The First Challenge

When navigating back to a route you've already visited, the application fetches the data from the server again.

While this can be addressed in several ways—such as implementing a cache or using a global store to maintain state across route transitions—there’s another, more nuanced issue.

The Second Challenge: Losing DOM State

When navigating away from a route, you lose all DOM state. This is particularly problematic with forms. When you return to the form, any entered data, validation states, and UI modifications are lost:

Although proper state management could solve this, it’s not straightforward. You’d need to:

Save the component state.
Reapply all DOM modifications to restore the previous look and behavior.

This involves patching form values, states, errors, and more. And it’s not limited to forms—other UI elements like accordions also require similar treatment.

Fortunately, Angular provides a powerful tool to address this: the RouteReuseStrategy class.

RouteReuseStrategy: what does it do?

You’ll find plenty of in-depth articles on RouteReuseStrategy, but here’s the gist: it allows you to control when Angular should dispose of or retain a component during navigation.

In our scenario, we want Angular to “set aside” (hide) components instead of destroying them when leaving a route, and to retrieve them as-is when navigating back.

By default, Angular uses an internal strategy, but we can override it with a custom implementation.

Creating a Custom Reuse Strategy

Here’s how we can define a custom RouteReuseStrategy:

@Injectable({
  providedIn: 'root',
})
export class CustomReuseStrategy implements RouteReuseStrategy {}

// main.ts
bootstrapApplication(AppComponent, {
  providers: [
    // ...
    {
      provide: RouteReuseStrategy,
      useExisting: CustomReuseStrategy,
    },
  ],
});

Note: Marking it as Injectable isn’t strictly required since Angular handles it internally, but this approach offers flexibility—more on that in a moment.

Defining Route Reuse Behavior

Let’s establish a convention for managing routes:

Use storeRoute: true for routes that should not be destroyed.
Use noReuse: true for routes that must not reuse components, even if the paths are identical.

The noReuse flag is critical for routes with parameters (e.g., /users/1 vs. /users/2). Without it, these routes would share the same component instance, leading to unintended state sharing.

Here’s how your routes might look:

const routes: Routes = [
  {
    path: 'users',
    component: UsersComponent,
    data: {
      storeRoute: true,
    },
  },
  {
    path: 'users/:id',
    component: UserComponent,
    data: {
      noReuse: true,
      storeRoute: true,
    },
  },
  {
    path: '**',
    redirectTo: '/users',
  },
];

A couple of helpers

For our implementation we'll need a couple of helpers:

A function which constructs the full path of a route, in order to identify it
A function which compares two objects, for comparing parameters and query parameters

Here an example for both:

function compareObjects(a: any, b: any): boolean {
  return Object.keys(a).every(prop => 
    b.hasOwnProperty(prop) &&
    (typeof a[prop] === typeof b[prop]) &&
    (
      (typeof a[prop] === "object" && compareObjects(a[prop], b[prop])) ||
      (typeof a[prop] === "function" && a[prop].toString() === b[prop].toString()) ||
      a[prop] == b[prop]
    )
  );
}

// Returns the full path of a route, as a string
 export function getFullPath(route: ActivatedRouteSnapshot): string {
  return route.pathFromRoot
    .map(v => v.url.map(segment => segment.toString()).join("/"))
    .join("/")
    .trim()
    .replace(/\/$/, ""); // Remove trailing slash
}

Implementing `RouteReuseStrategy`

Let's implement the class. First, we must create an object to cache our components:

import {
  ActivatedRouteSnapshot,
  DetachedRouteHandle,
  RouteReuseStrategy
} from "@angular/router";

interface StoredRoute {
  route: ActivatedRouteSnapshot;
  handle: DetachedRouteHandle;
}

@Injectable({
  providedIn: 'root'
})
export class CustomReuseStrategy implements RouteReuseStrategy {
  storedRoutes: Record<string, StoredRoute | null> = {};
}

I won't go into details about DetachedRouteHandle, but that's what will bring our component back when the route is visited again.

Now we must implement the required methods of RouteReuseStrategy.

A shouldDetach method decides whether to detach a route or not: we'll decide based on the storeRoute property in our route configuration.

  // Should we store the route? Defaults to false.
  shouldDetach(route: ActivatedRouteSnapshot): boolean {
    return !!route.data['storeRoute'];
  }

A store method allows us to store our route when navigating away from it. We'll store it by full path with our helper from before:

  // Store the route
  store(
    route: ActivatedRouteSnapshot,
    handle: DetachedRouteHandle
  ): void {
    // Ex. users/1, users/2, users/3, ...
    const key = getFullPath(route);
    this.storedRoutes[key] = { route, handle };
  }

A shouldAttach method decides whether to grab the route from our cache or not. Here, we compare all route parameters, including queryParams.

  // Should we retrieve a route from the store?
  shouldAttach(route: ActivatedRouteSnapshot): boolean {
    const key = getFullPath(route);
    const isStored = !!route.routeConfig && !!this.storedRoutes[key];

    if (isStored) {
      // Compare params and queryParams.
      // Params, however, have already been compared because the key includes them.
      const paramsMatch = compareObjects(
        route.params,
        this.storedRoutes[key]!.route.params
      );
      const queryParamsMatch = compareObjects(
        route.queryParams,
        this.storedRoutes[key]!.route.queryParams
      );

      return paramsMatch && queryParamsMatch;
    }
    return false;
  }

A retrieve method is used to grab the route from our cache:

  // Retrieve from the store (it only needs the handle)
  retrieve(route: ActivatedRouteSnapshot) {
    const key = getFullPath(route);
    if (!route.routeConfig || !this.storedRoutes[key]) return null;
    return this.storedRoutes[key].handle;
  }

Finally, shouldReuseRoute decides whether a route with the same path as the previous one should be reused. Again, we'll refer to our convention, and true will be the default:

  // Should the route be reused?
  shouldReuseRoute(
    previous: ActivatedRouteSnapshot,
    next: ActivatedRouteSnapshot
  ): boolean {
    const isSameConfig = previous.routeConfig === next.routeConfig;
    const shouldReuse = !next.data['noReuse'];
    return isSameConfig && shouldReuse;
  }

Convenience methods for purging the cache

It's important to understand that when a route is cached, the associated component is never destroyed. This also means that ngOnInit will not be triggered again when the user navigates back to the route. While this can be beneficial for preserving state, it also introduces the risk of memory leaks if not handled properly.

To mitigate this, I recommend implementing convenience methods to manually purge the cache: one for clearing a single route and another for clearing all routes.

  // Destroys the components of all stored routes
  clearAllRoutes() {
    for (const key in this.storedRoutes) {
      if (this.storedRoutes[key]!.handle) {
        this.destroyComponent(this.storedRoutes[key]!.handle);
      }
    }
    this.storedRoutes = {};
  }

  // Destroys the component of a particular route.
  clearRoute(fullPath: string) {
    if (this.storedRoutes[fullPath]?.handle) {
      this.destroyComponent(this.storedRoutes[fullPath].handle);
      this.storedRoutes[fullPath] = null;
    }
  }

  // A bit of a hack: manually destroy a particular component.
  private destroyComponent(handle: DetachedRouteHandle): void {
    const componentRef: ComponentRef<any> = (handle as any).componentRef;
    if (componentRef) {
      componentRef.destroy();
    }
  }

Conclusion

Here's the end result:

When navigating back to a cached route, the component retains all of its state seamlessly. Additionally, you can manually clear the cache whenever needed.

This solution is highly "plug-and-play" and can be easily integrated into your projects. However, use it wisely—improper use can make your app prone to memory leaks.

Link to the full demo here.

AccademiaDev: text-based web development courses!

Angular's inject function: a couple of years later...

Michele Stieven — Sun, 19 Jan 2025 23:50:42 +0000

Angular 14 introduced a new inject() function, offering an alternative to constructors for injecting dependencies.

export class MyComponent {
  myService = inject(MyService);
}

This brought several advantages, such as:

Easier inheritance

inject simplifies inheritance by eliminating the need to call super() in subclasses and reducing boilerplate code. This is especially useful when dependencies are inherited:

export class A {
  x = inject(X);
  y = inject(Y);
}

export class B extends A {
  z = inject(Z);

  // No need for constructors,
  // no need to inject X and Y,
  // no need to call super()
}

Avoiding Parameter Decorators

Previously, when requesting a non-class dependency (e.g., an InjectionToken), the @Inject() decorator was often used:

export class A {
  constructor(@Inject(X) x: SomeType) {}
}

With inject, you can skip the decorator and enjoy automatic type inference, making the code more concise and type-safe:

export class A {
  x = inject(X); // Works even with an InjectionToken
}

Additionally, inject's second parameter lets you control options like Optional, SkipSelf, Self, and Host—all without needing extra decorators:

// Default options
x = inject(X, {
  optional: false,
  skipSelf: false,
  self: false,
  host: false
})

In short, inject is a convenient utility. And as we've seen time and time again, convenience often wins over best practices.

This was my concern when it was first introduced: inject could encourage practices that aren't ideal, especially for mid-level developers. As a consultant and trainer, I feared its misuse.

Now that a couple of years have passed, it’s a good time to reflect and see if these fears have materialized.

Classes lose their "purity"

One of the core principles of Dependency Injection (DI) is that dependencies are passed into the class, meaning the class doesn't need to "grab" them itself.

export class A {
  // x is passed like a parameter
  constructor(x: X) {}
}

This makes unit testing extremely simple, as it's easy to substitute the dependency with a mock or fake:

const x = getFakeX();
const a = new A(x);

// Do your tests...

With inject, however, this simplicity is no longer guaranteed. Now, you must assume that any Angular class could be using inject, so you can no longer pass dependencies directly like this. Instead, you need to rely on Angular’s testing helper, TestBed, which sets up an injector:

describe('A Component', () => {
  let fixture: ComponentFixture<A>;
  let component: A;

  beforeEach(() => {
    TestBed.configureTestingModule({
      declarations: [A],
      providers: [
        { provide: X, useValue: MockX }
      ]
    });

    fixture = TestBed.createComponent(A);
    component = fixture.componentInstance;
  });
});

While this introduces more verbosity, it’s manageable, and the simplicity of Angular’s DI system remains intact in terms of functionality. Moreover, TestBed is necessary for testing the component's DOM, so I don't consider this a real drawback.

Scattered dependencies

Previously, all dependencies were neatly listed in the constructor, making them easy to spot. With inject, however, dependencies can now be scattered throughout the class:

export class A {
  x = inject(X);

  // ... 100 lines of code later ...
  y = inject(Y);

  // ... 
  z = inject(Z);
}

In practice, developers often group their dependencies at the top of the class for clarity, so this issue rarely becomes a major problem. However, it does reduce the immediate visibility of dependencies within the class.

Hidden dependencies

The real concern arises with the ability to call inject inside another function, but only if that function is invoked at construction time. This enables patterns like the following:

export class A {
  x = thisFunctionUsesInject();
}

function thisFunctionUsesInject() {
  const x = inject(X);
  return x;
}

This pattern is gaining popularity due to its convenience. However, it comes with its own set of challenges:

Hidden Dependencies: The dependency is now hidden inside a function, making it less obvious to anyone reading the code. They might expect the function to be usable anywhere, but if it's not executed during the construction phase, it will throw an error. This assumes the reader has knowledge of how Angular’s DI system works.
Lack of Transparency: When inspecting the component, it's not immediately clear that there are any dependencies. To understand the component fully, you need to dive into the function that uses inject(). This introduces complexity, as the component may seem simpler than it actually is. Some developers have suggested naming these functions with an "inject" prefix to clarify the dependency injection relationship, but I don’t agree with that approach. Such naming could be misleading if the function returns something different than what is being injected.
Increased Testing Complexity: As with any other situation where dependencies are not directly visible, you'll still need to use TestBed for testing. But as established earlier, this is not a major issue in itself.

To wrap it up, while it's certainly a useful pattern, I suggest not to abuse it and use it with care, because it can make your code harder to grasp.

What is an Injection Context?

The inject function can only be used within an Injection Context, but what exactly does that mean? In practice, this refers to specific places where Angular manages the lifecycle and context of a class or function, allowing it to resolve dependencies. These places include:

Constructors
Property initializers
Guards
Interceptors
useFactory when declaring providers

It’s fairly straightforward to understand that inject works during class construction because the class itself is being instantiated, and Angular has control over the DI context. However, the fact that it can also be used in places like guards or interceptors can be more confusing. This is a concern I’ve seen materialize frequently in my role as a consultant and trainer.

A particularly confusing scenario I’ve encountered involves functional NgRx Effects, where inject() is used in a function which shouldn't have any arguments:

// Functional NgRx Effect injecting Actions
createEffect((actions$ = inject(Actions)) => actions$.pipe(...), {
  functional: true
});

Here’s the trick: you have to understand that an Injection Context is automatically set up when NgRx creates the effect. The key to this pattern is that the inner function takes no arguments, so we exploit this by setting a default parameter, which just happens to be an injected dependency.

This pattern is not easy to grasp, especially for newcomers. The idea that inject works without explicitly calling a constructor or using a class can be quite confusing, and many developers, particularly those new to Angular or DI systems, struggle with this.

Minor causes of frustration I've seen on the web

Missed opportunity for a better name?: When inject was first introduced, some developers pointed out that it's actually the Injector (not inject itself) that performs the dependency injection. As a result, a few suggested that a different name, like ask or retrieve, would better reflect the function’s role. Personally, I don’t see this as a major issue. The name inject aligns with naming conventions in other frameworks, and it doesn’t cause any confusion for me.
Isn't this a Service Locator?: Another concern raised by some developers is that inject might resemble the Service Locator anti-pattern rather than true Dependency Injection. While it can be convincingly argued that inject is not a Service Locator (as highlighted in this insightful article), I do understand where the confusion stems from. The reason is that inject shares some of the same drawbacks as Service Locators, such as hidden dependencies and testing challenges.

Personally, I don’t believe inject is a Service Locator, but it also doesn't feel like a "pure" form of Dependency Injection. It’s somewhere in between. But it’s worth noting that some of the same issues could arise even before inject was introduced—simply by using the Injector to retrieve dependencies directly. Perhaps even worse, but it was not a common pattern.

Takeaways

The new inject function has proven to be incredibly useful, simplifying certain aspects of writing Angular code. Overall, I’m quite fond of it and generally recommend it over constructor parameters. I believe it’s valuable to adhere to a single, consistent practice, making the codebase easier to understand.

However, Angular developers need to invest some time in understanding what an Injection Context is and where inject can be safely used. It also takes time to fully grasp some of the more subtle patterns, such as hidden dependencies or using dependencies as default values for function parameters.

Given these nuances, I believe that documentation websites should take extra care when explaining what constitutes an Injection Context. It’s important not to assume too much knowledge from developers and to clarify how and when inject should be used.

AccademiaDev: text-based web development courses!

Angular LAB: animating lists and using AnimationBuilder for imperative animations

Michele Stieven — Wed, 09 Oct 2024 18:08:12 +0000

Did you know that Angular includes a complex animation system? I find it especially useful when I want to animate elements when they enter the screen or when they get destroyed!

Also, you can use AnimationBuilder in order to imperatively play, pause or stop some custom animations! Let's see how it's done.

Creating a list

In this exercise we start by creating a list, something like this:

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <button (click)="addUser()">Add user</button>
    <ul>
    @for (user of users(); track user.id) {
      <li>{{ user.name }}</li>
    }
    </ul>
  `,
})
export class AppComponent {
  users = signal<User[]>([
    { id: Math.random(), name: 'Michele' }
  ]);

  addUser() {
    this.users.update(users => [...users, { id: Math.random(), name: 'New user' }]);
  }
}

Notice that we've included a button which adds a user to the list!

Animating the list

Now, what if we want to animate the new user which will be added? First, we want to tell Angular that we want to use its animation system by providing it in your main configuration:

import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';

bootstrapApplication(AppComponent, {
  providers: [
    provideAnimationsAsync(),
  ]
});

Then, we can create our animation:

import { trigger, transition, style, animate } from '@angular/animations';

const fadeInAnimation = trigger('fadeIn', [
  transition(':enter', [
    style({ transform: 'scale(0.5)', opacity: 0 }),
    animate(
      '.3s cubic-bezier(.8, -0.6, 0.2, 1.5)', 
      style({ transform: 'scale(1)', opacity: 1 })
    )
  ])
])

With these helpers we:

Created an animation trigger called fadeIn
Added a transition when the element enters the screen
Applied an initial style
Immediately started the animation which will result in a new style applied to the element

For more information on how to write animations, you can refer to the official guide which is awesome!

Now let's apply this animation to each of our elements in the list:

@Component({
  ...,
  template: `
    <button (click)="addUser()">Add user</button>
    <ul>
    @for (user of users(); track user.id) {
      <li @fadeIn>{{ user.name }}</li> <!-- Notice here -->
    }
    </ul>
  `,
  // Also, add the animation to the metadata of the component
  animations: [fadeInAnimation]
})

Now, when a new item is added, it gets animated! Our first step is done.

Notice that in order for our animation to work correctly, Angular has to track each element in our for, because otherwise it could end up re-creating the same elements when updating the template, resulting in unwanted animations. This comes for free with the new Control Flow syntax because the track property is mandatory, but if you're using old verisons of Angular with the *ngFor directive, you must use the trackBy option like this:

<li
  *ngFor="let user of users; trackBy: trackByUserId"
  @fadeIn
>{{ user.name }}</li>

// A class method in your component:
trackByUserId(index, user: User) {
  return user.id;
}

Now, let's add another type of animation to our list.

AnimationBuilder

Let's add a button to each element of our list:

<li @fadeIn>
  {{ user.name }}
  <button>Make me blink</button>
</li>

Imagine this: we want to make the element blink when we press the button. That'd be cool! This is where the AnimationBuilder service comes in.

First, let's create a Directive which will be applied to every element. In this directive, we'll inject both ElementRef and AnimationBuilder:

import { AnimationBuilder, style, animate } from '@angular/animations';

@Directive({
  selector: '[blink]',
  exportAs: 'blink', // <--- Notice
  standalone: true
})
export class BlinkDirective {

  private animationBuilder = inject(AnimationBuilder);
  private el = inject(ElementRef);
}

Notice that we exported the directive: we'll get to the reason in a few seconds.

Then, we can create a custom animation like this:

export class BlinkDirective {

  ...

  private animation = this.animationBuilder.build([
    style({ transform: 'scale(1)', opacity: 1 }),
    animate(150, style({ transform: 'scale(1.1)', opacity: .5 })),
    animate(150, style({ transform: 'scale(1)', opacity: 1 }))
  ]);
}

We're using the same functions that we used in the previous animation, just with different styles.

Now we want to create a player which will perform the animation on our element:

export class BlinkDirective {

  ...

  private player = this.animation.create(this.el.nativeElement);
}

And now let's expose a method which will actually start the animation!

export class BlinkDirective {

  ...

  start() {
    this.player.play();
  }
}

There's only one step left: we must import the directive, apply it to our elements, grab it with a template variable and call the method when the button is pressed!

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <button (click)="addUser()">Add user</button>
    <ul>
    @for (user of users(); track user.id) {
      <li @fadeIn blink #blinkDir="blink">
        {{ user.name }}
        <button (click)="blinkDir.start()">Make me blink</button>
      </li>
    }
    </ul>
  `,
  imports: [BlinkDirective],
  animations: [
    fadeInAnimation
  ]
})

We can grab the directive's instance and put it in a local variable because we previously exported the directive with exportAs. That's the key part!

Now, try clicking on the button: the element whould be animated correctly!

The exercise is complete, but this is just the tip of the iceberg! The AnimationPlayer has a lot of commands which you can use to stop, pause and resume the animation. Very cool!

interface AnimationPlayer {
  onDone(fn: () => void): void;
  onStart(fn: () => void): void;
  onDestroy(fn: () => void): void;
  init(): void;
  hasStarted(): boolean;
  play(): void;
  pause(): void;
  restart(): void;
  finish(): void;
  destroy(): void;
  reset(): void;
  setPosition(position: number): void;
  getPosition(): number;
  parentPlayer: AnimationPlayer;
  readonly totalTime: number;
  beforeDestroy?: () => any;
}

Here's our full example if you want to play with it: just put it in your main.ts file and see it in action!

import { Component, signal, Directive, ElementRef, inject } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { trigger, transition, style, animate, AnimationBuilder } from '@angular/animations';
import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';

interface User {
  id: number;
  name: string;
}

@Directive({
  selector: '[blink]',
  exportAs: 'blink',
  standalone: true
})
export class BlinkDirective {

  private animationBuilder = inject(AnimationBuilder);
  private el = inject(ElementRef);

  private animation = this.animationBuilder.build([
    style({ transform: 'scale(1)', opacity: 1 }),
    animate(150, style({ transform: 'scale(1.1)', opacity: .5 })),
    animate(150, style({ transform: 'scale(1)', opacity: 1 }))
  ]);

  private player = this.animation.create(this.el.nativeElement);

  start() {
    this.player.play();
  }
}

const fadeInAnimation = trigger('fadeIn', [
  transition(':enter', [
    style({ transform: 'scale(0.5)', opacity: 0 }),
    animate(
      '.3s cubic-bezier(.8, -0.6, 0.2, 1.5)', 
      style({ transform: 'scale(1)', opacity: 1 })
    )
  ])
])

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <button (click)="addUser()">Add user</button>
    <ul>
    @for (user of users(); track user.id) {
      <li @fadeIn blink #blinkDir="blink">
        {{ user.name }}
        <button (click)="blinkDir.start()">Make me blink</button>
      </li>
    }
    </ul>
  `,
  imports: [BlinkDirective],
  animations: [
    fadeInAnimation
  ]
})
export class App {
  users = signal<User[]>([
    { id: Math.random(), name: 'Michele' }
  ]);

  addUser() {
    this.users.update(users => [...users, { id: Math.random(), name: 'New user' }]);
  }
}

bootstrapApplication(App, {
  providers: [
    provideAnimationsAsync()
  ]
});

AccademiaDev: text-based web development courses!

Angular LAB: let's create a Visibility Directive

Michele Stieven — Wed, 09 Oct 2024 00:05:23 +0000

In this article I'm going to illustrate how to create a very simple Angular Directive that keeps track of an element's visibility state, or in other words, when it goes in and out of the viewport. I hope this will be a nice and perhaps useful exercise!

In order to do this, we're going to use the IntersectionObserver JavaScript API which is available in modern browsers.

What we want to achieve

We want to use the Directive like this:

<p
  visibility
  [visibilityMonitor]="true"
  (visibilityChange)="onVisibilityChange($event)"
>
  I'm being observed! Can you see me yet?
</p>

visibility is the selector of our custom directive
visibilityMonitor is an optional input which specifies whether or not to keep observing the element (if false, stop monitoring when it enters the viewport)
visibilityChange will notifies us

The output will be of this shape:

type VisibilityChange =
  | {
      isVisible: true;
      target: HTMLElement;
    }
  | {
      isVisible: false;
      target: HTMLElement | undefined;
    };

Having an undefined target will mean that the element has been removed from the DOM (for example, by an @if).

Creation of the Directive

Our directive will simply monitor an element, it will not change the DOM structure: it will be an Attribute Directive.

@Directive({
  selector: "[visibility]",
  standalone: true
})
export class VisibilityDirective implements OnInit, OnChanges, AfterViewInit, OnDestroy {
  private element = inject(ElementRef);

  /**
   * Emits after the view is initialized.
   */
  private afterViewInit$ = new Subject<void>();

  /**
   * The IntersectionObserver for this element.
   */
  private observer: IntersectionObserver | undefined;

  /**
   * Last known visibility for this element.
   * Initially, we don't know.
   */
  private isVisible: boolean = undefined;

  /**
   * If false, once the element becomes visible there will be one emission and then nothing.
   * If true, the directive continuously listens to the element and emits whenever it becomes visible or not visible.
   */
  visibilityMonitor = input(false);

  /**
   * Notifies the listener when the element has become visible.
   * If "visibilityMonitor" is true, it continuously notifies the listener when the element goes in/out of view.
   */
  visibilityChange = output<VisibilityChange>();
}

In the code above you see:

the input and output we talked about earlier
a property called afterViewInit$ (an Observable) which will act as a reactive counterpart to the ngAfterViewInit lifecycle hook
a property called observer which will store the IntersectionObserver in charge of monitoring our element
a property called isVisibile which will store the last visibility state, in order to avoid re-emitting the same state twice in a row

And naturally, we inject the ElementRef in order to grab the DOM element on which we apply our directive.

Before writing the main method, let's take care of the lifecycle of the directive.

ngOnInit(): void {
  this.reconnectObserver();
}

ngOnChanges(): void {
  this.reconnectObserver();
}

ngAfterViewInit(): void {
  this.afterViewInit$.next();
}

ngOnDestroy(): void {
  // Disconnect and if visibilityMonitor is true, notify the listener
  this.disconnectObserver();
  if (this.visibilityMonitor) {
    this.visibilityChange.emit({
      isVisible: false,
      target: undefined
    });
  }
}

private reconnectObserver(): void {}
private disconnectObserver(): void {}

Now here's what happens:

Inside both ngOnInit and ngOnChanges we restart the observer. This is in order to make the directive reactive: if the input changes, the directive will start behaving differently. Notice that, even if ngOnChanges also runs before ngOnInit, we still need ngOnInit because ngOnChanges doesn't run if there are no inputs in the template!
When the view is initialized we trigger the Subject, we'll get to this in a few seconds
We disconnect our observer when the directive is destroyed in order to avoid memory leaks. Lastly, if the developer asked for it, we notify that the element has been removed from the DOM by emitting an undefined element.

IntersectionObserver

This is the heart of our directive. Our reconnectObserver method will be the one to start observing! It'll be something like this:

private reconnectObserver(): void {
    // Disconnect an existing observer
    this.disconnectObserver();
    // Sets up a new observer
    this.observer = new IntersectionObserver((entries, observer) => {
      entries.forEach(entry => {
        const { isIntersecting: isVisible, target } = entry;
        const hasChangedVisibility = isVisible !== this.isVisible;
        const shouldEmit = isVisible || (!isVisible && this.visibilityMonitor);
        if (hasChangedVisibility && shouldEmit) {
          this.visibilityChange.emit({
            isVisible,
            target: target as HTMLElement
          });
          this.isVisible = isVisible;
        }
        // If visilibilyMonitor is false, once the element is visible we stop.
        if (isVisible && !this.visibilityMonitor) {
          observer.disconnect();
        }
      });
    });
    // Start observing once the view is initialized
    this.afterViewInit$.subscribe(() => {
        this.observer?.observe(this.element.nativeElement);
    });
  }

Trust me, it's not as complicated as it seems! Here's the mechanism:

First we disconnect the observer if it was already running
We create an IntersectionObserver and define its behavior. The entries will contain the monitored elements, so it will contain our element. The property isIntersecting will indicate if the element's visibility has changed: we compare it to the previous state (our property) and if it's due, we emit. Then we store the new state in our property for later.
If visibilityMonitor is false, as soon as the element becomes visible we disconnect the observer: its job is done!
Then we have to start the observer by passing our element, so we wait for our view to be initialized in order to do that.

Lastly, let's implement the method which disconnects the observer, easy peasy:

 private disconnectObserver(): void {
    if (this.observer) {
      this.observer.disconnect();
      this.observer = undefined;
    }
  }

Final code

Here's the full directive. This was just an exercise, so be free to change it to whatever you like!

type VisibilityChange =
  | {
      isVisible: true;
      target: HTMLElement;
    }
  | {
      isVisible: false;
      target: HTMLElement | undefined;
    };

@Directive({
  selector: "[visibility]",
  standalone: true
})
export class VisibilityDirective
  implements OnChanges, OnInit, AfterViewInit, OnDestroy {
  private element = inject(ElementRef);

  /**
   * Emits after the view is initialized.
   */
  private afterViewInit$ = new Subject<void>();

  /**
   * The IntersectionObserver for this element.
   */
  private observer: IntersectionObserver | undefined;

  /**
   * Last known visibility for this element.
   * Initially, we don't know.
   */
  private isVisible: boolean = undefined;

  /**
   * If false, once the element becomes visible there will be one emission and then nothing.
   * If true, the directive continuously listens to the element and emits whenever it becomes visible or not visible.
   */
  visibilityMonitor = input(false);

  /**
   * Notifies the listener when the element has become visible.
   * If "visibilityMonitor" is true, it continuously notifies the listener when the element goes in/out of view.
   */
  visibilityChange = output<VisibilityChange>();

  ngOnInit(): void {
    this.reconnectObserver();
  }

  ngOnChanges(): void {
    this.reconnectObserver();
  }

  ngAfterViewInit(): void {
    this.afterViewInit$.next(true);
  }

  ngOnDestroy(): void {
    // Disconnect and if visibilityMonitor is true, notify the listener
    this.disconnectObserver();
    if (this.visibilityMonitor) {
      this.visibilityChange.emit({
        isVisible: false,
        target: undefined
      });
    }
  }

  private reconnectObserver(): void {
    // Disconnect an existing observer
    this.disconnectObserver();
    // Sets up a new observer
    this.observer = new IntersectionObserver((entries, observer) => {
      entries.forEach(entry => {
        const { isIntersecting: isVisible, target } = entry;
        const hasChangedVisibility = isVisible !== this.isVisible;
        const shouldEmit = isVisible || (!isVisible && this.visibilityMonitor);
        if (hasChangedVisibility && shouldEmit) {
          this.visibilityChange.emit({
            isVisible,
            target: target as HTMLElement
          });
          this.isVisible = isVisible;
        }
        // If visilibilyMonitor is false, once the element is visible we stop.
        if (isVisible && !this.visibilityMonitor) {
          observer.disconnect();
        }
      });
    });
    // Start observing once the view is initialized
    this.afterViewInit$.subscribe(() => {
        this.observer?.observe(this.element.nativeElement);
    });
  }

  private disconnectObserver(): void {
    if (this.observer) {
      this.observer.disconnect();
      this.observer = undefined;
    }
  }
}

DEV Community: Michele Stieven

Hallucinating Castles

The Project

The "Simple" Test

This is Happening More and More

The Angular pattern that needs no Provider

The component-scoped service

The host directive

A custom inject function

Why the call location matters

When should you use this pattern?

Give Your Angular Modal a URL: Three Router-Based Approaches

Why route a modal at all?

First rule: the URL as the source of truth

Option 1: a query parameter

Opening it

Keeping MatDialog in sync

Why replaceUrl when closing?

When query parameters work well

Option 2: a child path

A route component that opens the dialog

Avoid hard-coding the parent when needed

When a child path works well

Option 3: an auxiliary route

Route configuration

Why auxiliary routes are special

The cost

Material dialog or plain HTML?

What about route inputs and signals?

A practical comparison

A few rules that apply to all three

Final thought

Choosing the right RxJS Operator for Action Streams

The familiar effect

First: what are we flattening?

mergeMap: run everything

concatMap: queue everything

switchMap: keep listening only to the latest

exhaustMap: ignore repeated triggers

Do not choose by HTTP verb alone

Loading one replaceable collection

Loading a collection with query parameters

Loading individual entities

Keyed concurrency with groupBy

A groupBy lifetime warning

Creating entities

Updating entities

Deleting entities

A practical decision table

Should we hide this in a custom operator?

Final thought

Recreating LinkedIn’s Crossclimb Game with Angular - Part 3

The Hint component

The Container

Showing the edge words

The middle words

Where to go from here

Recreating LinkedIn’s Crossclimb Game with Angular - Part 2

The models

The service

The derived states

Recreating LinkedIn’s Crossclimb Game with Angular - Part 1

How the game works

The Word component

The template

Handling the keydown event

The Icon component

Next steps

Angular Authentication with Cookies in 10 minutes

AccademiaDev: text-based web development courses!

Before we begin: the server

Step 1: Getting the CSRF Token

Step 2: Sending the Cookie in localhost

Step 3: Creating a service

Step 4: Detect an expired cookie

Step 5: Guard your pages!

Use it!

Bonus: SSR Quirks

Angular LAB: Preserving Component State Across Route Transitions

The First Challenge

Keeping `MatDialog` in sync

Why `replaceUrl` when closing?

`mergeMap`: run everything

`concatMap`: queue everything

`switchMap`: keep listening only to the latest

`exhaustMap`: ignore repeated triggers

Keyed concurrency with `groupBy`

A `groupBy` lifetime warning

The `Hint` component

The `Word` component

Handling the `keydown` event

The `Icon` component

Step 2: Sending the Cookie in `localhost`

Implementing `RouteReuseStrategy`