Forem: Ayyash

Putting Angular Fire Firestore library to use - II

Ayyash — Tue, 04 Feb 2025 10:00:00 +0000

Previously we created our own Firestore getters to return proper observables, using from to change a Promise into a cold observable. Today let's go on with other commands to map our data properly.

Mapping data

Now that we don't rely on rxfire to return mapped document id, we're going to create our own converters.

"Firestore has a built in converter withConverter to map to and from FireStore. No thanks. We'll take it from here."

The getDoc() returns the DocumentSnapshot with id, and data() as above. getDocs() returns a QuerySnapshot with docs array, among other things, which is an array of DocumentSnapshot objects returned. Our category model now looks like this:

// category.model

// mapping new instance
export interface ICategory {
  name: string | null;
  id: string | null;
  key?: string;
}

// static class or export functions, it's a designers choice
export class Category {
  public static NewInstance(data: QueryDocumentSnapshot): ICategory {
    if (data === null) {
      return null;
    }
    const d = data.data();
    return {
      id: data.id,
      name: d['name'],
      key: d['key']
    };
  }

  // receives QuerySnapshot and maps out the `data() ` and id
  public static NewInstances(data: QuerySnapshot): ICategory[] {
    // read docs array 
    return data.docs.map(n => Category.NewInstance(n));
  }

}

So the service call now looks like this:

// category.service

 GetCategories(params: IWhere[] = []): Observable<ICategory[]> {
    // ...
    return from(getDocs(_query)).pipe(
      map((res: QuerySnapshot) => {
        // here map
        return Category.NewInstances(res);
      })
    );
}
GetCategory(id: string): Observable<ICategory> {
    return from(getDoc(doc(this.db, 'categories', id))).pipe(
      map((res: DocumentSnapshot) => {
        // map
        return Category.NewInstance(res);
      }),
    );
}

Let's see what addDoc() returns.

Create document

I created a quick form with name and key, to add category, and a service call to create category:

// components/categories.list

addNew() {
    // read form:
    const newCat: Partial<ICategory> = this.fg.value;

    this.categoryService.CreateCategory(newCat).subscribe({
      next: (res) => {
        // the category list should be updated here
       console.log(res);
      }
    });
}

The service is expected to return an observable, the following may not cut it, the returned object is a DocumentReference which only is a reference to the document created with id.

// category.service
CreateCategory(category: Partial<ICategory>): Observable<any> {
    return from(addDoc(collection(this.db, 'categories'), category)).pipe(
      map(res => {
        // I have nothing but id!
        return {...category, id: res.id};

      })
    );
}

That may look fine, but I do not wish to use id directly without going through our mappers, the solution can be as simple as a separate mapper, or we can slightly adapt the NewInstance

// category.model

// adjust NewInstance to accept partial category
public static NewInstance(data: DocumentSnapshot | Partial<ICategory>, id?: string): ICategory {
    if (data === null) {
      return null;
    }

    const d = data instanceof DocumentSnapshot ? data.data() : data;
    return {
      id: data.id || id, // if data.id doesnt exist (as in addDoc)
      name: d['name'],
      key: d['key']
    };
}

Then in the service call we pass the original category with the returned id

// category.service

CreateCategory(category: Partial<ICategory>): Observable<ICategory> {

    return from(addDoc(collection(this.db, 'categories'), category)).pipe(
      map(res => {
        // update to pass category and res.id
        return Category.NewInstance(category, res.id);
      }),
    );

}

The curious case of Firestore syntax

The following methods are so identical, if you do not make distinction between them you might lose your hair before 50. So I decided to list them, then forget them.

doc(this.db, 'categories', 'SOMEID') returns DocumentReference, of new or existing document
doc(collection(this.db, 'categories')) returns DocumentReference of newly generated ID
setDoc(_DOCUMENT_REFERENCE, {...newCategory}, options) sets the document data, saves with the provided ID in the Document Reference
addDoc(collection(this.db, 'categories'), {...newCategory}); adds a document with an auto generated ID (this is shortcut for doc(collection...) then setDoc())
updateDoc(doc(this.db, 'categories', 'EXISTING_ID'), PARTIAL_CATEGORY) this updates an existing document (a shortcut for doc(db...) then setDoc() with an existing ID)

The confusion stirred up from the first two, they look so similar, but they are different

// Find document reference, or create it with new ID
const categoryRef = doc(this.db, 'categories', '_SomeDocumentReferenceId');

// Create a document reference with auto generated id
const categoryRef = doc(collection(this.db, 'categories'));

Now the returned reference document can be used to create an actual document, or update it. So it is expected to be succeeded with setDoc

// then use the returned reference to setDoc, to add a new document
setDoc(categoryRef, {name: 'Bubbles', key: 'bubbles'});

// pass partial document with options: merge to partially update an existing document
setDoc(existingCategoryRef, {name: 'Bubble'}, {merge: true});

If the document does not exist wit merge set to true, it will create a new document with partial data. Not good. Be careful.

The safe options are the last two:


// add a new documnet with a new generated ID
addDoc(collection(this.db, 'categories'), {name: 'Bubbles', key: 'bubbles'});

// update and existing document, this will throw an error if non existent
updateDoc(existingCategoryRef, {name: 'Bubbles'})

For illustration purposes, here is the other way to create a new category

// an alternative way to create
CreateCategory(category: Partial<ICategory>): Observable<ICategory> {

    // new auto generated id
    const ref = doc(collection(this.db, 'categories'));

    return from(setDoc(ref, category)).pipe(
       map(_ => {
         // response is void, id is in original ref
         return Category.NewInstance(category, ref.id);
       })
    );
}

Update document

Building on the above, I created a quick form for the category details to allow update. I will still pass all fields, but we can always pass partial fields.

// category.sevice

// id must be passed in category
UpdateCategory(category: Partial<ICategory>): Observable<ICategory> {
    return from(updateDoc(doc(this.db, 'categories', category.id), category)).pipe(
      map(_ => {
        // response is void
        // why do we do this? because you never know in the future what other changes you might need to make before returning
        return Category.NewInstance(category);
      })
    );
}

This is a proof of concept, there are ways to tighten the loose ends, like forcing the id to be passed, checking non existent document, returning different shape of data, etc.

To use it, the form is collected, and the id is captured:

// categories/list.component
update(category: ICategory) {
    // gather field values
    const cat: Partial<ICategory> = this.ufg.value;

    // make sure the id is passed
    this.categoryService.UpdateCategory({...cat, id: category.id}).subscribe({
      next: (res) => {
        console.log(res); // this has the same Category after update
      }
    });
  }

Delete document

This one is straight forward, we might choose to return a Boolean for success.

// category.sevice

DeleteCategory(id: string): Observable<boolean> {
    return from(deleteDoc(doc(this.db, 'categories', id))).pipe(
      // response is void, but we might want to differentiate failures later
      map(_ => true)
    );
}

We call it simply by passing ID

// category/list.component

delete(category: ICategory) {
    this.categoryService.DeleteCategory(category.id).subscribe({
      next: (res) => {
        console.log('success!', res);
      }
    });
}

There is no straight forward way to bulk delete. Let's move on.

Querying responsibly

We created an IWhere model to allow any query to be passed to our category list. But we should control the fields to query in our models, and protect our components from field changes. We should also control what can be queried and how, in order to always be ahead of any hidden prices on Firebase.

In our IWhere model, we can add IFieldOptions model. Here is an example of label instead of name, to show how we protect our components from Firestore changes.

// where.model

// the param fields object (yes its plural)
export interface IFieldOptions {
    label?: string; // exmaple
    key?: string;

    // other example fields
    month?: Date;
    recent?: boolean;
    maxPrice?: number;
}


// map fields to where conditions of the proper firestore keys

export const mapListoptions = (options?: IFieldOptions): IWhere[] => {

    let c: any[] = [];
    if (!options) return [];

    if (options.label) {
      // mapping label to name
      c.push({ fieldPath: 'name', opStr: '==', value: options.label });
    }

    if(options.key) {
      c.push({ fieldPath: 'key', opStr: '==', value: options.key });
    }
    // maxPrice is a less than or equal operator
    if (options.maxPrice) {
        c.push({ fieldPath: 'price', opStr: '<=', value: options.maxPrice });
    }

    if (options.month) {
        // to implement, push only data of the same month
        c.push(...mapMonth(options.month));
    }

    if (options.recent) {
        const lastWeek = new Date();
        lastWeek.setDate(lastWeek.getDate() - 7);
        // things that happened since last week:
        c.push({ fieldPath: 'date', opStr: '>=', value: lastWeek });
    }

    return c;
}

The change on our service is like this

// category.sevice

// accept options of specific fields
GetCategories(params?: IFieldOptions): Observable<ICategory[]> {
    // translate fields to where:
    const _where: any[] = (mapFieldOptions(fieldOptions))
        .map(n => where(n.fieldPath, n.opStr, n.value));

    // pass the where to query
    const _query = query(collection(this.db, this._url), ..._where);

    // ... getDocs
}

Here is an example of how to get a group of documents by maximum price:

// example usage
something$ = someService.GetList({maxPrice: 344});

This makes much more sense. I added an example of date, note that operations on JavaScript date works fine, even if the Firestore date is of type Timestamp. The idea of the example is to showcase that the component should not really know the details of the implementation, so getting "most recent documents" for example should be like this

// example
something$ = someService.GetList({recent: true});

The other example is to get month of date, Firestore deals with Javascript date directly:

// where.model

const mapMonth = (month: Date): IWhere[] => {
  const from = new Date(month);
  const to = new Date(month);

  from.setDate(1);
  from.setHours(0, 0, 0, 0);
  to.setMonth(to.getMonth() + 1);
  to.setHours(0, 0, 0, 0); // the edge of next month, is last day this month


  let c: IWhere[] = [

    { fieldPath: 'date', opStr: '>=', value: from },
    { fieldPath: 'date', opStr: '<=', value: to }
  ];

  return c;
};

This works as expected.

Timestamp

Firestore reference of Timestamp.

This class may not make a difference when querying, but if you have a date field, and would like to save user provided date into it, it's best to use Firestore Timestamp class to do the conversion. The difference between Firestore Timestamp and Javascript date is subtle. So subtle I don't even see it! I think it's the ranks of rounding.

// somemodel

// use Timestamp class to map from and to dates

const jsDate = new Date();

// addDoc with
const newData = {
    fbdate: Timestamp.fromDate(jsDate)
}

// DocumentSnapshot returns data() with date field, the type is Timestamp
// use toDate to convert to js Date
return data['fbdate'].toDate();

Firestore Lite

Firebase offers a lite version of Firestore for simple CRUD, so far we have used only those available in lite version. I changed all
import { ... } from '@angular/fire/firestore';
Into
import { ... } from '@angular/fire/firestore/lite';

The build chunk was indeed smaller. The main chunk that was reduced in my personal project, came down from 502 KB to 352 KB.

Interception

With httpClient we used an interception function to add the loading effect, so how do we do that with our solution? We can funnel all calls to one http service that takes care of it. Our new service should be something around this:

// http.service

@Injectable({ providedIn: 'root' })
export class HttpService {
  public run(fn: Observable<any>): Observable<any> {

    // show loader here
    showloader();

    // return function as is
    return fn
      .pipe(
        // hide loader
        finalize(() => hideloader()),
        // debug and catchErrors as well here
      );
  }
}

Then in the service

// category.service

private httpService = inject(HttpService);

GetCategories(params?: IWhere[]): Observable<ICategory[]> {
    // ...
    // wrap in run
    return this.httpService.run(from(getDocs(q)).pipe(
      map((res: QuerySnapshot) => {
        return Category.NewInstances(res);
      })
    ));
}

One design problem in the above is the loss of type checking because the inner function returns observable<any>. This can be fixed with a generic

// http.service
// ...
public run<T>(fn: Observable<any>): Observable<T> {
    // ...
}

Then call it like this:

// category.service
return this.httpService.run<ICategory[]>(from(getDocs(q)).pipe(
  map((res: QuerySnapshot) => {
    return Category.NewInstances(res);
  })
));

Have a look at the loading effect we created previously using state management. All we need is to inject the state service, then call show and hide. This uses good ol' RxJs, I looked into Signals, and could not see how it would replace RxJs without making a big mess. May be one fine Tuesday.

That's it. Don't lose hair before 50.

Did you catch the pants on fire? Keep talking. It's not over yet.

Resources

Creating a loading effect using RxJs in Angular

Putting Angular Fire Firestore library to use - II - Sekrab Garage

Angular Firebase Firestore. Previously we created our own Firestore getters to return proper observables, using from to change a Promise into a cold observable. Today let's go on with other commands to map our data properly.Ma.... Posted in Angular, Design

garage.sekrab.com

Putting Angular Fire Firestore library to use - I

Ayyash — Tue, 28 Jan 2025 10:00:00 +0000

In this series, we're going to setup a project that uses a Firebase Firestore to list, create, and edit documents, in Angular. This article:

... is about Angular project architecture, about observables, and promises
... is not about Firebase setup or maintenance
... is not about firebase authentication (find here)
... uses the official @angular/fire package

With the latest Angular update, along with Angular Fire, was kind of depressing. I understand the need to be ever-green, I just don't understand throwing away a syntax that works, for another trendy syntax! But, here we are.

Setup

Here find a link to Firebase Firestore setup, and to Angular Fire setup.

Follow along this project on StackBlitz. I removed Firebase configuration so it won't run properly.

Let's create a project that lists cateogires, where every category is made up of:

name
key

Like this

The main.ts contains the bootstrapper as follows:

// main.ts 

// pay attention to where the imports are from, it should from @angular/fire
import { initializeApp, provideFirebaseApp } from '@angular/fire/app';
import { getFirestore, provideFirestore } from '@angular/fire/firestore';

const fbApp = () => initializeApp({
    //... firebaseConfig here
});
// ... optionally add authentication 

const firebaseProviders = [
  provideFirebaseApp(fbApp),
  provideFirestore(() => getFirestore()),
];

bootstrapApplication(AppComponent, {
  providers: [
    ...firebaseProviders,
    // ...otherpoviders
  ]
})

The Firestore reference

Angular Fire library initializes the db using getFirestore(app); and makes it available for injection.

In a service; the category service, the class looks like this

// services/category.service.ts

@Injectable({ providedIn: 'root' })
export class CategoryService {
    // inject
    private db: Firestore = inject(Firestore);
}

The db is ready to be used in categoryService.

Note about referencing the right SDK

If you run into this error:

"FirebaseError: Type does not match the expected instance. Did you pass a reference from a different Firestore SDK?"

Make sure you were using the latest Firebase libraries. The ones that worked for me were firebase 11.2.0 and @angular/fire 19.0.0 along with @angular/core 19.0.6 minimum.

Get data

Working backwards, what we want to end up with is a component that consumes a returned list as follows:

// a consuming component, like categories list

@Component({
    //...
    template: `@let cats = categories$ | async`
})
export class CategoryListComponent implements OnInit {

    // example
    categories$: Observable<ICategory[]>;
    private categoryService = inject(CategoryService);

    ngOnInit(): void {
        // get categories from service, I expecct an observable I can async to
        this.categories$ = this.categoryService.GetCategories();
    }
}

To get data we use collectionData which returns and observable. The collection function itself returns a reference to the collection.

// services/category.service.ts

@Injectable({ providedIn: 'root' })
export class CategoryService {
    // inject, or via constructor
    private db: Firestore = inject(Firestore);

    GetCategories(): Observable<ICategory[]> {
        // collectionData returns a hot observable
        return collectionData(collection(this.db, 'categories')).pipe(
            map((response: any) => {
                // map the returnd docs into your ICategory
                // i am not including this part here
                return Category.NewInstances(response);
            })
        );
    }
}

did you know you can import from @angular/fire/firestore/lite instead? This is firestore lite library for simple REST and GRUD actions.

The collectionData itself is an HOT observable exported from the rxfire library by Firebase. The following list is already wrapped and exported by @angular/fire

// wrapped and exported by angular fire, from rxFire
  auditTrail,
  collection,
  collectionChanges,
  collectionCount,
  collectionCountSnap,
  collectionData,
  doc,
  docData,
  fromRef,
  snapToData,
  sortedChanges

The returned observable is hot, it's actually so hot, it's cross user, cross browser. Which is not ideal in most of the cases. Under the hood: I spotted this line in the rxfire library
RxFire ref: import('firebase/database').Query,

Yes, they import from the real-time database!

One way to fix that is to pipe to take(1) or first()

// categories.service

GetCategories(): Observable<ICategory[]> {
    // collectionData returns a hot observable
    return collectionData(collection(this.db, 'categories')).pipe(
        // turn off
        first(),
        map((response: any) => {
            // ...
        })
    );
}

Later we'll figure out a better way.

Getting the document id

The above returns an array of categories without document id.. Let's compare the official documentation with that of AngularFire. According to Firestore documentation

// as documented
getDocs(collection(this.db, 'categories')).then(
  (s) => {
    // this returns .id, and .data()
    s.forEach(f => console.log(f.id))
  }
);

Our solution uses rxFire collectionData, which under the hood is an observable wrapped around DocumentSnapshot The function expects options that can have a mapper to the idField, which is a way to wrap both id and data() in one object. One of Firebase's mysteries!

// services/category.service.ts

GetCategories(): Observable<ICategory[]> {
    // map id as well with idField
    return collectionData(collection(this.db, 'categories'), {idField: 'id'}).pipe(
        // turn off hot observable
        first(),
        // ... map
    );
}

We can use the result to build our list, with links to every category.

// category/list.component
template:`@let cats = categories$ | async;
<ul>
  <li *ngFor="let cat of cats">
    <a (click)="select(cat)">{{cat.name}}</a>
  </li>
</ul>

<div class="c-6 box bg-white" *ngIf="selected$ | async as cat">
    selected Category: {{cat | json}}
</div>
`

selected$: Observable<ICategory>;

select(category: ICategory) {
    // to implement GetCategory
    this.selected$ = this.categoryService.GetCategory(category.id);
}

Get by document ID

To get a single category by document ID, according to AngulareFire, you just pass categories/:id. But that isn't how it looks.

I get a different hint in the official documentation

const docRef = doc(db, "cities", "SF");
const docSnap = await getDoc(docRef);

You can always think of collection is the table, and doc as the single row.

To get a collection, or a sub collection, use collectionData with URL syntax that has odd number of segments
categories/:id/something

To get a document, anywhere, we must use docData, and the URL should have even number of segments
categories/:id/something/:somethingid

So if you do not adhere to the number of segments in the URL, for example using collectionData to get two segments, you will get funny error messages like this:

Collection references must have an odd number of segments, but categories/RG3e5jWzithsEzoPWBag has 2.

The right way is to use doc and docData instead.

// category.service
GetCategory(id: string): Observable<ICategory> {
    // pass url: categories/:id, or pass arguments separately
    return docData(doc(this.db, 'categories', id), { idField: 'id' }).pipe(
      first(),
      // ... map
    );
}

Query

To get a list of categories based on any criteria, we use query, then collectionData. The result is always an array.

// category.service

// query to get all categories
const _query = query(collection(this.db, 'categories'))

return collectionData(_query, { idField: 'id' }).pipe(
    first(),
  // ... map
);

Adding a where condition of multiple fields, the default is an AND operator, the reference format is query(ref, where(), where() ...)

// categories.service

// multiple field where condition
GetCategories(params: IWhere[]): Observable<ICategory[]> {

    // turn params into an array of where conditions, then expand it
    const _query = query(collection(this.db, 'categories'), 
    ...params.map(n => where(n.fieldPath, n.opStr, n.value))
    );

    return collectionData(_query).pipe(
        first(),
        // ... map
    );
}

The or format looks like this: query(ref, or(where(), where() ...), and a combination may look like this query(ref, and(where(), where(), or(where(), where()...) ...)

Find reference here

Now the where conditions are made up of three segments: field, operator, value. So in another model file, we define the interface:

// where.model.ts
export type IWhereOp =
    | '<'
    | '<='
    | '=='
    | '!=' // be careful, some operators are not free
    | '>='
    | '>'
    | 'array-contains'
    | 'in' 
    | 'array-contains-any'
    | 'not-in';

export interface IWhere {
    fieldPath: string;
    opStr: IWhereOp;
    value?: any;
}

To use it, we pass the where conditions:

// categories/list.component

this.categories$ = this.categoryService.GetCategories(
    [
        {fieldPath: 'key', opStr: '==', value: 'household'}
    ]
);

This looks ugly all around. Later we'll figure out a more useful way.

Creating a new category is passing the object to addDoc, but the catch is, there is no observable to watch. This is a Promise. But we want an observable so we can pipe to properly.

At this stage, I want to stop and take a step back. The above solutions used rxfire observables, which are all hot. It is not ideal to keep hot observables when dealing with a very expensive service like Firestore. We used first to cool it off. But let's try something different. In order to use with all actions.

Cold observables

Using collectionData and docData is a bit disappointing, because not all actions are wrapped inside of it, and they are hot! We can use from. Or defer if we use then directly. Let me show you both ways:

Using from

// categories.service

// getDocs imported from @angular/fire
// get data with "from"
return from(getDocs(q)).pipe(
  map((s: any) => {
    // s is a querysnapshot that has forEach method
    s.forEach(n => console.log(n.data()));
    // we'll map later
    return s;
  })
);

Or you can use then directly if you remember to defer in RxJs (because then invokes an immediate call):

// categories.sevice

// a different way
const docs = () => getDocs(q).then(s => {
  console.log(s);
  return s;
});

// return a defer in order to subscribe to
return defer(docs)

I like the from way. So I am sticking to it

Mapping data

Let's figure out a way to:

map our data properly with document ID
show a loading effect (yes)

Before we go on, let's see if that fixed the add document mess:

// categories.service

  CreateCategory(category: Partial<ICategory>): Observable<any> {
    return from(addDoc(collection(this.db, 'categories'), category));
    // todo: proper mapping
  }

Yup, this works as expected. But there are other ways to add documents. Next Tuesday inshallah. 😴

Did you know that the IOF destroyed 80% of Gaza? But Gaza will recover.

References:

garage.sekrab.com

Angular Firebase Authentication Update: v.19

Ayyash — Tue, 21 Jan 2025 10:15:00 +0000

Last time we had Firebase Auth integrated at Angular 17. Here is a quick update to keep it fresh in Angular 19.

Providers

Before update, our main.ts looked like this

// main.ts before
const fbApp = () => initializeApp(firebaeConfigHere);
const authApp = () => initializeAuth(fbApp(), {
  persistence: browserSessionPersistence,
  popupRedirectResolver: browserPopupRedirectResolver
});

const firebaseProviders: EnvironmentProviders = importProvidersFrom([
  provideFirebaseApp(fbApp),
  provideAuth(authApp),
]);

bootstrapApplication(AppComponent, {
  providers: [
      // ...
    firebaseProviders
  ],
});

The updates touch the importProvidersFrom, it not longer is needed

// main.ts thew new

const firebaseProviders = [
  provideFirebaseApp(fbApp),
  provideAuth(authApp),
];

bootstrapApplication(AppComponent, {
  providers: [
    // expand it
    ...firebaseProviders
  ],
});

APP_INITIALIZER token

One way to inject the AuthState on application start was to use the APP_INITIALIZER token with no return, and one injection, like this

  {
    provide: APP_INITIALIZER,
    // dummy factory
    useFactory: () => () => {},
    multi: true,
    // injected depdencies, this will be constructed immidiately
    deps: [AuthState],
  },

This simply becomes this:

// new provider
  provideAppInitializer(() => {
    inject(AuthState);
    return null;
  }),

That's it. Looks like the new Firebase library still works as designed.

Validation style final tweaks

Ayyash — Fri, 17 Jan 2025 10:00:00 +0000

To add the missing styles to make it as functional as possible, need to keep reminding ourselves of a golden rule:

Do not assume.

This means we can add relative paddings and margins, borders and colors, using CSS variables, but we cannot dictate how the checkbox should look like. That’s a project style, not an element style. (There are schools like material design that stuff their noses into every element, making it impossible to use single components individually.)

Checkbox

Starting with the checkbox, all we need to do is swap locations of checkbox and label. Then just let the outer project design its own checkbox instead. There are two solutions, a smart one, and a too smart one. The too smart one looks like this:

.cr-field {
   /* target previous silbing */
  .cr-label:has(~ [type="checkbox"]) {
    /* important to remove transform in all cases */
    transform: none!important;
    inset-block-start: 0;
    inset-inline-start: 0;
    padding-inline-start: 1.8rem;
    position: relative;
    display: inline-block;
    background: none;
    cursor: pointer;
  }

  .cr-input[type="checkbox"] {
    position: absolute;
    inset-inline-start: 0;
  }
}

The simpler way is to introduce a new type property for the cr-field directly, assigned explicitly. Implicit assignment is also "too smart."

// input.partial
template: `
    <div class="{{ cssPrefix }}-field {{ typeCss }}" [class.cr-invalid-form]="invalidForm">
    // ...
`
@Input() type!: string;

get typeCss(): string {
    return this.type ? `${this.cssPrefix}-${this.type}` : '';
}

Then we write a not too-smart CSS:

.cr-field.cr-checkbox {
  .cr-label {
   /* same as above */
  }
  .cr-input {
   /* same as above */
  }
}

The selector is simpler and we have a bit more room to style other things, like the required asterisk, the help text, and the feedback text. See, sometimes it pays off to be dumber.

The CSS for this solution:

.cr-field.cr-checkbox {
  .cr-label {
    /* important to remove transform in all cases */
    transform: none!important;
    inset-block-start: 0;
    inset-inline-start: 0;
    padding-inline-start: 1.8rem;
    position: relative;
    display: inline-block;
    background: none;
    cursor: pointer;
  }
  .cr-input {
    position: absolute;
    inset-inline-start: 0;
  }
  .cr-feedback {
    margin-block-start: 0;
    float: none;
  }
  .cr-required {
    position: static;
  }
}

Testing the edges

One of the scenarios we went through is where the required asterisk was out of view, we already designed it to be positioned on the extreme right. With what we have so far, can we make it look good without touching the library component and shared css?

Here is the example of Expiry date, the solution to place the asterisk within context is simply add enough style to the container.

/* fix the container width to be c-5 and display block */
<cr-input placeholder="Expiration" error="Add a date in the future" class="c-5 dblock">
  <input type="hidden" crinput id="mmyy" [required]="true" pattern="[0-9]{4}" formControlName="mmyy" />
  /* also fix the width of inner fields to c-6 */
  <cr-product-expiry (onValue)="expirationValue($event)"></cr-product-expiry>
</cr-input>

The result is like this:

Three things I’ve done:

Changed the container width to be at the percentage width I desired, and changed its display to block (Angular components display by default as contents )
I changed the inner component width to be 50% each (makes more sense)
Then changed the message to: Add a date in the future. This covers both rules: expired date and required value.

So our component held. No changes needed. That is a victory.

You may need to test extra scenarios and update the input css to be as simple as possible, so that it won’t break in the future.

Testing another edge case: Nice looking checkbox

Here is another edge case. Every project has its own style for checkboxes. Given the CSS we have developed thus far, let's see if we can push our single checkbox from the outside world without breaking it. Let's use MDN example.

/* adding the same css with a proper random selector to our project */
.gr-something .cr-field.cr-checkbox {

  .cr-input {
    /* remove default appearance **/
    appearance: none;
    width: 44px;
    height: 24px;
    border-radius: 12px;
    transition: all 0.4s;
  }
  .cr-input::before {
    width: 16px;
    height: 16px;
    border-radius: 9px;
    background-color: var(--sh-black, #000);
    content: '';
    position: absolute;
    inset-block-start: 3px;
    inset-inline-start: 4px;
    transition: all 0.4s;
  }
  .cr-input:checked {
    background-color: var(--sh-yellow, #ffaa00);
    transition: all 0.4s;
  }
  .cr-input:checked::before {
    inset-inline-start: 22px;
    transition: all 0.4s;
  }
  .cr-label {
    /* adjust padding of label */
    padding-inline-start: 4.2rem;
  }
}

The above is the MDN example with few adjustments. We just had to pay attention to the selector so that we don't resolve to !important issues. Applying it is as easy as applying class to selector:

<cr-input  type="checkbox" class="gr-something" ...>
    <input type="checkbox" crinput  ...>
</cr-input>

This looks like the following:

Another victory! See, if we were too smart about our selectors, this would have turned into spaghetti.

Hidden fields

Hidden inputs simplify validation, that would otherwise be challenging. If the validation is within context of the cr-field it’s straight forward, like our previous example of the Expiration date.

<cr-input placeholder="Expiration" error="This is expired">
  <input type="hidden" crinput id="mmyy" pattern="[0-9]{4}" formControlName="mmyy" />
  // some component with MM and YY fields
  <cr-product-expiry (onValue)="expirationValue($event)"></cr-product-expiry>
</cr-input>

If the hidden input is not within context of a field, and it carries out a cross-form update and validation, then the cr-field has nothing but the feedback. The solution is to introduce the type hidden.

Here is a quick example, let’s say if the operating system is MAC, the minimum version is 5.

// example form components
<div class="spaced">
  <cr-input placeholder="Operating system">
    <select crinput id="os" formControlName="os" [required]="true" (change)="updatePlug()">
      <option value="">Select</option>
      <option value="1">Windows</option>
      <option value="2">Mac</option>
      <option value="3">Linux</option>
      <option value="4">Android</option>
    </select>
  </cr-input>
</div>

<cr-input placeholder="Version">
  <input crinput type="number" id="version" formControlName="version" (change)="updatePlug()" />
  <ng-container helptext>OS version</ng-container>
</cr-input>

Updating the fields updates a hidden field plugs with either a value or null

template: `  
// ...
<cr-input placeholder="" error="Not allowed to have Mac version less than 5">
  <input type="hidden" crinput id="plugs" formControlName="plugs" [required]="true" >
</cr-input>`

// in code
updatePlug() {
  // on change of form input, update hidden field
  const os = this.fg.get('os').value;
  const version = this.fg.get('version').value;
  if (os === '2' && version < 5) {
    this.fg.get('plugs').setValue(null);
  } else {
    this.fg.get('plugs').setValue('plug'+ os + version);
  }
}

So the only thing I want to take care of is hiding the required asterisk, and making the feedback more of a none-floating element. Any other styling, need to happen outside the component.

// let's pass type:hidden
<cr-input type="hidden" error="Not allowed to have Mac version less than 5">
  <input type="hidden" crinput id="plugs" formControlName="plugs" [required]="true" >
</cr-input>

And we cater for the cr-hidden style:

// input.css
.cr-field.cr-hidden {
  .cr-label {
    display: none;
  }
  .cr-input[required] ~ .cr-required {
    display: none;
  }
  .cr-feedback {
    float: none;
    margin-block-start: 0;
    margin-inline-start: 0;
  }
}

This will look like this

Of course, my validation is a bit dumbed down for demonstration purposes. The hidden field can have any validation (a pattern for example), you can use setErrors instead of setValue, and you can customize the error message accordingly. That would not affect the CSS though.

Auto-filled fields

The last problem to fix is auto-filled fields, like username and password, where you don’t want the placeholder label to appear on top of the field. Ever. To fix that we introduce a new type static to prevent the floating animation.

Although this isn't stubborn but it would be nice to have another style for none-floating labels in general.

<cr-input placeholder="Username" type="static">
    <input crinput type="text" autocomplete="username" id="username"
     formControlName="username" [required]="true" />
</cr-input>
<cr-input placeholder="Password" type="static">
    <input crinput type="password" autocomplete="current-password" id="pwd" 
    formControlName="pwd" [required]="true" />
</cr-input>

The CSS then defines the new type:

/* input.css */
.cr-field.cr-static {
  /* force floating label even if empty */
  .cr-label:has(~ .cr-input:placeholder-shown) {
    transform: translateY(-100%) scale(0.8);
  }
}

And this is as good as it gets. Notice that if emptied, that label will not float inside the field. Meh, cheap price.

That's it. This is a wrap.

Bonus: standalone imports

Another thing we can do to make this easier to use, is place them in an exported const to import together.

export const InputComponent = [
  InputDirective,
  CrInputPartial
];

Then we can import then together

// in our component
// ...
imports: [...InputComponent],

Conclusion

To recap, the initial target was the following:

Use native HTML input elements.
We did, with only the introduction a formControlName and a directive
Validation rules should be kept to minimum
We only manipulated the error message, and contained basic patterns and common functions
Keep the Angular form loose (do not reinvent the wheel)
The input is content-projected, it belongs to the original form
Use attributes instead of Form builder (unobtrusive)
A directive that reads different attributes was accomplished
Keep form submission loose to allow as much flexibility
Since the form is not part of our directive, nothing is imposed on it
Minimum styling allowing full replacement.
We tried. I think we managed.

That's it. Let Gaza Live.

Resources

StackBlitz project

Validation style final tweaks - Sekrab Garage

Taming Angular forms. To add the missing styles to make it as functional as possible, need to keep reminding ourselves of a golden rule:Do not assume.This means we can add relative paddings and margins, borders and colors,.... Posted in Angular, Design

garage.sekrab.com

Angular validation common functions

Ayyash — Wed, 15 Jan 2025 10:00:00 +0000

There are some repetitive validation functions that I would like to move for their own common file, after which, I want to turn the validation function into another unobtrusive pattern.

The final result should look like this

<cr-input placeholder="placeholder">
  <input crinput ... validator="functionName" />
</cr-input>

Let’s create popular validators and see what it takes.

Date

The date and time fields are handled by browsers pretty well; they don’t need a lot of work. What we need to cover in our patterns is future dates, past dates, and date ranges.

// final result I want to work with
<cr-input placeholder="When?">
  <input crinput type="date" id="appointment" formControlName="appointment" 
    validator="future" />
  <ng-container helptext>Future date</ng-container>
</cr-input>

Let’s change validator attribute into a validation function. We will follow the same method of patterns.

// new validators.ts

export const futureValidator = (control: AbstractControl): ValidationErrors | null => {
  // date is yyyy-mm-dd, should be int eh future
  const today = Date.now();

  if (!control.value) return null;
  const value = new Date(control.value);

  if (!value || +value > +today) {
    return null;
  }
  return {
    future: true
  };
};

// create a map to use globally
export const InputValidators = new Map<string, ValidatorFn>([
  ['future', futureValidator],
]);

In the directive, we’ll check if the validation function already exists. If not, we’ll add it.

// input.directive

// add a new input
@Input() validator?: string;

// in validate handler, just add it
validate(control: AbstractControl): ValidationErrors | null {

  if (this.validator) {
    const _validator = InputValidators.get(this.validator);
    if (_validator && !control.hasValidator(_validator)) {
      control.addValidators(_validator);
    }
  }
  // ... 
}

There is another way to access the form input. However, it relies on having formControl defined and casting an Abstract control to a Form control. It’s ugly. And dependent on the form itself. I’m not using.

That’s it. We don’t need to validate. Then we just need to add a custom error message every time. For now that’s fine.

<cr-input placeholder="When?" error="Required and must be in the future">
  <input crinput type="date" id="appointment" formControlName="appointment" 
    validator="future" [required]="true" />
  <ng-container helptext>Future date</ng-container>
</cr-input>

A past date is straight forward.

Enrich the inline validator

We can improve it a bit, let’s pass parameters unobtrusively too, like this

<input crinput type="date" id="birthdate" formControlName="birthdate" validator="pastFn"
[params]="{date: someDate}"  />

someDate = new Date(2000, 1, 1);

That is what I call garnish, let’s add it, but let’s be very careful. If we ever have to fix a bug in it, we roll back to good old custom validation. I fixed a couple as I was writing this article! I suggest you implement your favorite method.

 // input.directive
@Input() validator?: string;
@Input() params?: any;

validate(control: AbstractControl): ValidationErrors | null {
    if (this.validator) {
        const _validator = InputValidators.get(this.validator);
        if (_validator && !control.hasValidator(_validator)) {
            // if params: apply function (note here params is no longer optional)
            if (this.params) {
                control.addValidators(_validator(this.params));
            } else {
                control.addValidators(_validator);
            }
        }
    }
    // ...
}

Then in our validators collection, wrap the function in another function to pass the arguments. Notice how I choose to name it with Fn suffix, to remind myself it's a function that needs params. (We might enhance by making the params optional and have a different check, but I am not well motivated to do that.)

// vaidtaors.ts

// example pastvalidation with date
export const pastValidatorFn = (params: {date: string}): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    if (!control.value) return null;

    const _date = makeDate(params.date);
    if(!_date) return null;

    const value = new Date(control.value);
    if (!value || +value < +_date) {
      return null;
    }
    return {
      past: true
    };
  };
};

// add to collection, the second argument of map is "any"
// if you want to reach 50s without a heart attack
export const InputValidators = new Map<string, any >([
    // ...
  ['pastFn', pastValidatorFn],
]);

So far so good. The date range should now be easy, all we need to do is update the validation functions to accept two parameters, minimum and maximum. If one is null, it’s ever.

// validator.ts
// A generic function for date ranges, fix it as you see fit
export const dateRangeValidatorFn = (params: {minDate?: string, maxDate?: string}): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    if (!control.value) return null;

    // make two dates if one is null, the other takes over, if both null, return null.
    const _min = makeDate(params.minDate);
    const _max = makeDate(params.maxDate);
    if (!_min && !_max) return null;

    // if both exist, range
    // if only one exists, check against that
    const _minDate = _min ? +_min : null;
    const _maxDate = _max ? +_max : null;
    const value = +(new Date(control.value));

    const future = _maxDate ? value < _maxDate : true;
    const past = value > _minDate; // null is also zero, so this works
    if (future && past) {
      return null;
    }

    return {
      dateRange: true
    };
  };
};

// add to map
export const InputValidators = new Map<string, ValidatorFn>([
    // ...
  ['dateRangeFn', dateRangeValidatorFn],
]);

Since we are passing params as an object, there is enough dynamic behavior to it, but I haven’t fully tested it.

Form component

<cr-input placeholder="Date range" error="Out of range">
    <input crinput type="date" id="daterange" class="w100" formControlName="daterange" [params]="params" validator="dateRangeFn"  />
    <ng-container helptext>Between 1 Jan 2024 - 1 Jan 2025</ng-container>
</cr-input>

minDate = new Date(2024, 0, 1);
maxDate = new Date(2025, 0, 1);
params = { minDate: this.minDate, maxDate: this.maxDate };

A date range selector.

Oh no. Use easypick. By far the least obtrusive. I hope they continue the path of “keeping this dead simple”

Password

To do this properly in our new validators shared function, it needs to pass the other field value dynamically. So we start with a function and a param.

// in the new validators.ts
export const matchPasswordFn = (pwd: AbstractControl): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    // get password and match, if equal return null
    if (control?.value === pwd?.value) {
      return null;
    }
    return {
      matchPassword: true
    };
  };
};

The two fields in our component before using the validator property looks like this

// compontent
template: `
  <cr-input placeholder="Password">
     <!-- update validity on change -->
     <input crinput type="password" id="pwd" (change)="fg?.get('pwd2')?.updateValueAndValidity()"
     formControlName="pwd" crpattern="password" [required]="true" />
    <ng-container helptext>Alphanumeric and special characters, 8 characters minimum</ng-container>
  </cr-input>

  <cr-input placeholder="Confirm password" error="Does not match" >
    <input crinput type="password" id="pwd2" formControlName="pwd2" [required]="true" />
    <ng-container helptext>Should match password</ng-container>
  </cr-input>`

  // in class, before 
  ngOnInit() {
    this.fg = this.fb.group({
      pwd: [''],
      // this won't work
      // pwd2: ['', matchPasswordFn(this.fg.get('pwd')],
      pwd2: ['']
    });

    // this will (import from validators)
    this.fg.get('pwd2').setValidators(matchPasswordFn(this.fg.get('pwd')));
  }

Few things to notice:

Setting the validator directly in the form builder won’t work, because we need to access the form itself, which is not yet available.
We could have done a cross-form validation!
But because we did not, we needed to update validity of pwd2, whenever pwd changed. This is just to be as flexible as one can be.

We can import the matchPasswordFn directly from our validators function, but we can also use the validator property as follows:

// component

<cr-input placeholder="Confirm password" error="Does not match" >
    <!-- add the validator function directly -->
    <input crinput formControlName="pwd2" ...
        validator="matchPassword"
        [params]="fg?.get('pwd')"
    />
</cr-input>

And then the same validation function can be used.

Upload

We begin with a file input that is required. It does not look great, but I will not force it to look any different because every project will has its own unique look for this field. Some might also allow drag and drop, or paste. So we’ll focus on the basics.

Format and required validations are easy. We can create a general image pattern in our patterns list. Adding accept attribute is an additional friendly feature.

// patterns
export const InputPatterns = new Map<string, any>([
 //...
  ['image', '.+\\\\.{1}(jpg|png|gif|bmp)$'],
]);

The component looks like this

// component
<cr-input placeholder="Upload document">
  <input crinput type="file" id="file" formControlName="doc" crpattern="image"
  [attr.accept]="someArray" />
  <ng-container helptext>JPG, PNG only. 1 MB max.</ng-container>
</cr-input>

And it looks like this

The size is a bit harder to capture. But we can still use what we have. A new validation function that accepts two parameters, one for the maximum size, and one for the file size.

// validators
// validate file size to be what?
export const sizeValidatorFn = (params: {size: number, max: number}): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    if (!control.value) return null;
    // convert max from KB to bytes
    const _max = params.max * 1024;
    if (params.size > _max) {
      return {
        size: true
      };
    }

    return null;
  };
};

export const InputValidators = new Map<string, any >([
 // ...
  ['sizeFn', sizeValidatorFn]
]);

And to use it, we need something like this

// component
template: `<cr-input placeholder="Upload document" error="Invalid format or size">
  <input crinput type="file" id="file" class="w100" formControlName="doc" crpattern="image"
   #f validator="sizeFn" [params]="fparams" (change)="updateSize(f)" />
  <ng-container helptext>JPG, PNG only. 1 MB max.</ng-container>
</cr-input>`

fparams: { size: number, max: number };
this.fg = this.fb.group({
  doc: [],
});
updateSize(f: HTMLInputElement) {
    // update the params, then update validity
    // because files is not an immidiate property of formControl
    this.fparams.size = f.files[0]?.size;
    this.fg.get('doc').updateValueAndValidity();
}

This works as expected, but I think we can do better. The file input field is usually not part of the form, because the trend is to upload the file first to the cloud, then update our server record with the returned file unique identifier. We'll leave that to one fine Tuesday.

At least one

Let's add the "at least one" for group of checkboxes in there too.

// validators.ts
export const atleastOne = (control: AbstractControl): ValidationErrors | null => {
  // if all controls are false, return error

  const values = Object.values(control.value);
  if (values.some(v => v === true)) {
    return null;
  }

  return { atleastOne: true };
};

Then use directly in a group of checkboxes

// form component
<cr-input placeholder="Colors" error="At least one color" >
    <div formGroupName="colors" crinput validator="atleastOne">
      <label>
        <input type="checkbox" name="colors" id="color1" formControlName="red">
        Red
      </label> 
      <br>
      <label>
        <input type="checkbox" name="colors" id="color2" formControlName="black">
        Black
      </label> <br>
      <label>
        <input type="checkbox" name="colors" id="color3" formControlName="green">
        Green
      </label> <br>
    </div>
</cr-input>

That's enough.

Styling

In order to fine tune styling without making assumptions about the project style, nor using too smart CSS selectors, let's go back to few elements and dig deeper. Last episode. 😴

Did you speak up today?

References

StackBlitz project

Angular form field types

Ayyash — Mon, 13 Jan 2025 10:00:00 +0000

Today we are going to dig into validating all field types. We begin with the simpler ones: the string-based ones:

Email, tel, and text, are the easy ones; nothing that needs extra care
Textarea: This is like text input. It may need extra styling.
URL: This is not handled by Angular, so we can use a pattern matcher.
Number: The browser number field is powerful enough to prevent non-numeric values, but we can still use a pattern matcher for more control.

Other types are:

Select box: The only generic validation needed is required
Checkboxes and radio buttons: The most obvious validation is "at least one is selected"
Hidden fields: These are like text fields but need styling.

Textarea

This one is straightforward, the common validation is minimum and maximum number of characters, which is done via the native minlength and maxlength . This has already been covered. Looks like the style is also still holding.

Select box

The pain—or not! Using the first test: a list with “required” validation, the only missing thing we can style is the arrow. It begins with appearance: none. But that's a project-related choice.

UX tip: if it is required, select one by default.

Some high-security websites (like banking) mandate that the user makes a deliberate choice—whatever that means—but those were the exact words I was once told. In this case, an option with empty value acts as a null value and will trigger an invalid flag.

<cr-input placeholder="Operating system">
  <select crinput id="os" formControlName="os" [required]="true">
    <option value="">Select</option>
    <option value="1">Windows</option>
    <option value="2">Mac</option>
    <option value="3">Linux</option>
    <option value="4">Android</option>
  </select>
</cr-input>

This is how it looks when invalid

This actually worked better than I hoped for! Let’s move on.

Checkbox

For a single checkbox with required, functionally it works because it will be valid if true. But it looks awful. The label needs to be after the checkbox. Sucks doesn’t it?

// form component, the preferred syntax
<cr-input placeholder="Terms and conditions" error="Please accept">
  <input type="checkbox" name="accept" [required]="true" crinput id="accept" formControlName="accept">
</cr-input>
// ...
this.fg = this.fb.group({
    //...
    accept: [],
});

Won’t show you how it looks, we’ll fix all styles later. But it does work as expected.

Multiple checkboxes

There are a lot of ways to create a group of checkboxes with the same name. This article is not about that, but the end result I want to reach is a validation message that falls into place with other fields.

The four ways I know of are:

formGroupName with checkboxes
formArrayName with checkboxes
Checkboxes that update a validation state of the form
Checkboxes that update a hidden input that is part of the form

Here is a example of formGroupName that uses a cross-form validation function to set the state of the form as invalid. We make use of the invalidForm property to display the error.

// form componennt
template: `
  <cr-input placeholder="Colors" error="At least one color" [invalidForm]="fg.get('colors').hasError('atleastOne')">
    <div formGroupName="colors">
      <label>
        <input type="checkbox" name="colors" id="color1" formControlName="red">
        Red
      </label> <br>
      <label>
        <input type="checkbox" name="colors" id="color2" formControlName="black">
        Black
      </label> <br>
      <label>
        <input type="checkbox" name="colors" id="color3" formControlName="green">
        Green
      </label> <br>
    </div>
    <ng-container helptext>Choose at least one </ng-container>
  </cr-input>`

// ...
this.fg = this.fb.group({
  colors: this.fb.group({
    red: [],
    black: [],
    green: [],
  }, { validators: this.atleastOne})

});

atleastOne = (control: AbstractControl): ValidationErrors | null => {
  // if all controls are false, return error
  const values = Object.values(control.value);
  if (values.some(v => v === true)) {
    return null;
  }
  return { atleastOne: true };

};

The error shows when:
fg.get('colors').hasError('atleastOne')

It works, but it looks like the following. That, we’ll fix later.

We can also assign the directive to the formGroupName field, like this:

<cr-input placeholder="Colors" error="At least one color">
  // simply add crinput directive here
  <div formGroupName="colors" crinput>
    ...
  </div>
  <ng-container helptext>Choose at least one </ng-container>
</cr-input>

Keeping the validator as is, no need to use invalidForm. This validates nicely, and it looks as follows. A bit better.

Another way is to have the checkboxes separated in their own HTML element. This works as well if we want to display the bubble in a different location.

<cr-input placeholder="Colors" error="At least one color" [invalidForm]="fg.get('colors').hasError('atleastOne')">
    Select a color 
</cr-input>

<div formGroupName="colors">
    <label>
      <input type="checkbox" name="colors" id="color1" formControlName="red">
      Red
    </label> <br>
    <label>
      <input type="checkbox" name="colors" id="color2" formControlName="black">
      Black
    </label> <br>
    <label>
      <input type="checkbox" name="colors" id="color3" formControlName="green">
      Green
    </label> <br>
</div>

And it looks like this:

This is all possible because we kept it dead simple with the form feedback error class. We just need a bit more touch-ups, every project may have its own styling.

Radio button

As for radio buttons, they are bound to a single formControlName. The thing about radio buttons, is that the validation is almost always a cross-form validation. Best experience dictates that at least one should be checked by default. If none was checked by default, notice how by now we can use crinput directive on a normal HTML element, and get away with it. We use the invalidForm property to react to the invalid radio button.

<!-- add invalidForm to component -->
<cr-input placeholder="Gender" [invalidForm]="fg.get('gender').invalid">
  <!-- use crinpiut to div?! -->
  <div crinput>
    <input type="radio" name="gender" value="male" [required]="true"  id="male" formControlName="gender"> Male
    <input type="radio" name="gender" value="female" [required]="true" id="female" formControlName="gender"> Female
  </div>
</cr-input>

Looks as follows:

Let’s move on.

Hidden field

Hidden inputs simplify validation that would otherwise be challenging. They are mostly treated like text fields, with special styling. We will take care of that later.

Validation common functions

We created a patterns collection to reuse throughout our project, but we can also create common validation functions for reuse. Let's go through some common examples to build it up. Next episode, inshalla. 😴

Did you know that UNRWA is complicit in genocide?

Resources

Angular form field types - Sekrab Garage

Taming Angular forms. Today we are going to dig into validating all field types. We begin with the simpler ones: the string-based ones:<ul><li>Email, tel, and text, are the easy ones; nothing that needs extra care</li><li>.... Posted in Angular, Design

garage.sekrab.com

Angular form validation directive

Ayyash — Tue, 07 Jan 2025 10:05:00 +0000

The component we created thus far is enough to make the form invalid if submitted, and show the "required" balloon when the field is invalid. Following is other built in validations.

The final result is preferably an unobtrusive one like this:

<input crinput type="number" id="valvet" formControlName="valvet" [min]="3" [required]="true" />

Before we build the new crinput directive, the component itself can be enhanced.

We need to first add a location for the help text, and some new CSS. And a custom error property.

The error message belongs to our custom component but needs to be flexible and can be overwritten
The help text belongs to the project, don't even think about automating it
From user experience side, I believe stating the rule up front, then keeping the error message short is the best way to fill the form efficiently.

In our final HTML, this is where we want to get:

<!-- form template-->
<cr-input placeholder="Mars" error="Too small">
  <input crinput type="number" id="mars" formControlName="mars" [min]="2" />
  <ng-container helptext>Minimum of 2</ng-container>
</cr-input>

To reflect this in our input component, we use a new content selector

<!-- input.partial -->
<div class="{{ cssPrefix }}-field">
  <label class="cr-label" for="{{for}}">{{ placeholder }}</label>
  <ng-content></ng-content>
  <span class="cr-required"></span>
  <span class="cr-feedback">{{ error }}</span>
  <span class="cr-help">
    <!-- second content projection -->
    <ng-content select="[helptext]"></ng-content>
  </span>
</div>

And the CSS

.cr-field {
  /* ... */

  .cr-help {
    color: var(--sh-text-light, #959595);
    font-size: 90%;
    display: block;
    margin-block-start: var(--sh-halfspace, 0.8rem);
    text-align: end;
  }
  /* if there is nothing, hide it */
  .cr-help:empty {
    display: none;
  }
}

And finally the error message. That can be set as an input:

// input.partial
export class CrInputPartial implements AfterContentInit {
  // ...
  @Input() error: string;
}

Directive

The directive should implement Validator, the event to handle is

validate(control: AbstractControl): ValidationErrors | null

What we want to do is automate the error message based on the validation rule added, without canceling the validation. We need to provide the NG_VALIDATORS token to be able to implement Validator

// new lib/input/input.directive.ts

@Directive({
    selector: '[crinput]',
    // the "multi" allows the native validation to kick in first
    providers: [{provide: NG_VALIDATORS, multi: true, useExisting: InputDirective}]
})
export class InputDirective implements Validator {
    constructor() {}
    validate(control: AbstractControl): ValidationErrors | null {
    // to be implemented
    // set error text based on validation

    // then return null to continue with the native Angular validation
      return null;
    }
}

Back to our component, swap the ContentChild with the directive

// inut.partial

// ...
@ContentChild(InputDirective, { static: true }) inputDirective!: InputDirective;

Instead of having two content child definitions, one for the named element #crinput and one for the directive crinput, we can rely on the directive itself to get the element, and elevate it via a public property. Like this:

// input.directive
constructor(private el: ElementRef) {}

// the element is an HTML element of the input
public get element(): HTMLElement {
  return this.el.nativeElement;
};

In the input component

// input.component
export class CrInputPartial implements AfterContentInit {
  // we only need this
  @ContentChild(InputDirective, { static: true }) inputDirective!: InputDirective;

  ngAfterContentInit() {
    if (this.inputDirective) {
      const element = this.inputDirective.element;
      // if element exists:
      this.for = element.id;
      element.classList.add('cr-input');
      element.setAttribute('placeholder', this.placeholder);
    }
  }
}

So now we can remove the #crinput

<cr-input placeholder="Valvet">
  <input crinput type="text" id="valvet" formControlName="valvet" [required]="true" />
</cr-input>

The error message property

Let's start with the simple min validation. What we need is a way to read that property in the directive. One way to do that is to expose the min input.

// input.directive

// expose the min property
@Input() min?: number;

// create an error text property
private _error: string = 'Required';
public get errorText(): string {
    return this._error;
}
// ...
validate(control: AbstractControl): ValidationErrors | null {

    // if min exists
  if (this.min) {
    // change error message
    this._error = 'Too small';
  }
  // move on
  return null;
}

Then in the component

// input.component
template: `
  <div class="{{ cssPrefix }}-field">
    // ...
    <!-- use a new property errorText -->
    <span class="cr-feedback">{{ errorText }}</span>
  </div>
  `,

// keep error input
@Input() error: string;

// error text now is a combination
get errorText(): string {
  // get custom error or fall back to directive
  return this.error || this.inputDirective?.errorText;
}

The native validation kicks in afterwards. Let's add max input as well.

Edge case: min and max

If we test for both minimum and maximum at the same time, it won't quite work. We need to know which edge was the invalid edge.

<input crinput type="number" id="mars" formControlName="mars" [min]="2" [max]="5" />

In our validator, we need to validate using the native validation to see which edge was invalid.

 // input.directive

 // two inputs
@Input() min?: number;
@Input() max?: number;

// check which edge failed
if (this.min) {
  if (Validators.min(this.min)(control)) {
    this._error = 'Too small';
  }
}

// when max fails, change to message
if (this.max) {
  if (Validators.max(this.max)(control)) {
    this._error = 'Too large';
  }
}

There is one issue that blocked the process, and that is the errorText is not updating. The directive changes the value, but the component never picks up. Unless:

use ChangeDetectionStrategy.Default (nasty)
Join the Signal bandwagon (Finally, I have a proper use case!)

The errorText need to be a Signal.

// input.directive

@Input() min?: number;
@Input() max?: number;

// ...
// turn it into a signal
public errorText = signal('Required');
validate(control: AbstractControl): ValidationErrors | null {

  // when min fails, change to message
  if (this.min) {
    if (Validators.min(this.min)(control)) {
      this.errorText.set('Too small');
    }
  }

  // when max fails, change to message
  if (this.max) {
    if (Validators.max(this.max)(control)) {
      this.errorText.set('Too large');
    }
  }
  return null;
}

And the component now reads the signal:

// input.partial
get errorText(): string {
  // get custom error or fallback to directive error
  return this.error || this.inputDirective.errorText();
}

If it is also required, the message need to be reset. So reset to required on every validation. Also, we need to validate only when value is not null.

// directive
// slight adjustment to handle required as well
// always reset to required
this.errorText.set('Required');

// validate if value is not null
if (this.min && control.value) {
  if (Validators.min(this.min)(control)) {
    this.errorText.set('Too small');
  }
}

if (this.max && control.value) {
  if (Validators.max(this.max)(control)) {
    this.errorText.set('Too large');
  }
}

Reverse range

What if we want a truly custom validation, where the number should be outside range?

// directive
export class InputDirective implements OnInit, Validator {

  // simple array
  @Input() block?: [number, number];
    validate(control: AbstractControl): ValidationErrors | null {
      // ...
      if (this.block) {
        // its valid if the value is outside the block array
        if (control.value >= this.block[0] && control.value <= this.block[1]) {
          this.errorText.set('Invalid number');
          // one of the few times we need to return invalid
          return {
            block: true
          }
        }
      }
      return null;
  }
}

This is a sort of custom validation, so we need to return something, in this case block: true. You can complicate this further if you wish, but it's good enough for this project.

Length

It's quite similar to max and min:

// directive
@Input() minLength?: number;
@Input() maxLength?: number;

// in validate
if (this.minlength && control.value) {
  if (Validators.minLength(this.minlength)(control)) {
    this.errorText.set('Too short');
  }
}

if (this.maxlength && control.value) {
  if (Validators.maxLength(this.maxlength)(control)) {
    this.errorText.set('Too long');
  }
}

Pattern

Working backwards, the pattern is added as an attribute:

<!--html-->
<cr-input placeholder="Shortname">
  <input crinput type="text" id="shortname" formControlName="shortname"  pattern="[A-Za-z]{5}" />
  <ng-container helptext>Alphanumeric, 5 characters</ng-container>
</cr-input>

Then in our directive, we expose the pattern to change the error message:

// directive
@Input() pattern?: string;
validate(control: AbstractControl): ValidationErrors | null {
  // ...
  if(this.pattern) {
    this.errorText.set('Invalid format');
  }
  return null;
}

This might look enough. But this is our chance to reign our patterns. I would like my final result to look like this

<input crinput id="short-name" formControlName="phone" pattern="phone" />

The error message should be "Invalid short-name format", the specs of our new feature are:

'Phone' could be a look up that is constantly used, the message would be "invalid phone format"
Or it can be overwritten per project, the message would be "invalid format" or a custom error
Nice to have: allow the format to be added. Silliest way is: global const.
Or a simple rollback to default Angular pattern, the message would be "invalid format" or a custom error

First, we create a lookup for our phone pattern to be used globally.

Using pattern directly will fail, because it cannot be canceled if handled. And I will not dwell upon it much, overriding it or redefining the default behavior is not ideal. So we will stay away from the pattern attribute. We will create a new property: crpattern

// partial.directive

// new prop
@Input() crpattern?: string;

if(this.crpattern) {
  // the default
  this.errorText.set('Invalid format');
  // if pattern exists in our list (to be created), use validators
  let _pattern = InputPatterns.get(this.crpattern);
  if (_pattern) {
    this.errorText.set(`Invalid ${this.crpattern} format`);
      // now validate
    return Validators.pattern(_pattern)(control);
  }
}

We create a new file for the input patterns

// patterns.ts
export const InputPatterns = new Map<string, any>([
  ['phone', '[+\\d\\s]*'],
  ['password', '[\\S]{8,}']
]);

In our HTML, here are three scenarios that cover the requirements:

// form component

templtes: `
  <cr-input placeholder="Phone">
         <!-- A built-in phone format -->
    <input crinput type="text" id="phone" formControlName="phone" crpattern="phone" />
    <ng-container helptext>Alphabets and spaces</ng-container>
  </cr-input>
  <cr-input placeholder="Shortname">
      <!-- an adhoc new pattern -->
    <input crinput type="text" id="shortname" formControlName="shortname" crpattern="shortname" />
    <ng-container helptext>Alphanumeric, 5 characters</ng-container>
  </cr-input>
  <cr-input placeholder="Some pattern" error="Invalid koolaid format">
         <!-- native with a custom error -->
    <input crinput type="text" id="koolaid" formControlName="koolaid"  pattern="[1-9]{2,4}" />
    <ng-container helptext>Two to 4 numbers</ng-container>
  </cr-input>
  `
 // ...
 ngOnInit(): void {
  // add and adhoc pattern, this is forever
  InputPatterns.set('shortname', '[A-Za-z]{5}');

  // the form
  this.fg = this.fb.group({
    valvet: [''],
    mars: [1],
    buler: [],
    shortname: [],
    phone: [],
    koolaid: []
  });
// ...
}

This produces the following

So far so good. I'd rather use the silly way knowing that every project will have its own unique way to extend the formats. Personally, I would turn the patterns class into an abstract and override it locally.

Note about text

The ideal way is not to use the text in the directive directly but rather use a resources file. In my attempt to redefine localization in Angular, I came up with a Res class that reads the values off of a javascript file. But you can use your own translation solution to return the right message. My resources would look like this

"INVALID_phone_FORMAT": "Have you ever used a phone!",

Where shortname is the pattern key. The messages displayed in the directive would be:

this.errorText.set(Res.Get(INVALID_${this.crpattern}_FORMAT));

Email validation

It should be exactly similar to pattern, but according to the documentation, a sole attribute is enough: email. But because we need to map it, and read it, we should get into the habit of using an exact value. I choose boolean.

 <!--from component-->
 <cr-input placeholder="Email">
  <input crinput type="email" id="email" formControlName="email" [email]="true" />
  <ng-container helptext>Native email</ng-container>
</cr-input>

The validators

// input.directive
@Input() email?: boolean;

if(this.email) {
  this.errorText.set('Invalid email format');
}

Using the Angular native email validator is better, it keeps the email pattern up to date. But you will find yourself in situations where the pattern is too loose. For example email@example actually checks. In this case, use a custom crpattern instead.

Custom validation

This one has resolved itself. If we use a validation function, all we need now is to set a custom error message:

// form component
template: `
<cr-input placeholder="Custom name" error="Bob is not allowed">
  <input crinput type="text" id="koolaid" formControlName="name"  />
  <ng-container helptext>Not bob</ng-container>
</cr-input>
`

// inside class custom examle
forbiddenNameValidator = (nameRe: RegExp): ValidatorFn => {
  return (control: AbstractControl): ValidationErrors | null => {
    const forbidden = nameRe.test(control.value);
    return forbidden ? {forbiddenName: {value: control.value}} : null;
  };
}

// in form builder
name: ['',  this.forbiddenNameValidator(/bob/i)]

Cross form validation

In cross form validation things are not as clear. From user experience point of view, it isn't correct to place the error message out of context. There must be context. For example, password confirm validation, is a custom validation of the second input. Since we can have the function on the same page, the form value is available. So this has been covered. Here is the example in documentation.

// form
template: `
  <cr-input placeholder="Custom name" error="Bob is not allowed">
      <input crinput type="text" id="name" formControlName="name"  />
      <ng-container helptext>Not bob</ng-container>
    </cr-input>
    <cr-input placeholder="Role" error="Name cannot match role or audiences will be confused.">
      <input crinput type="text" id="role" formControlName="role"  />
    </cr-input>
`;

// in class
unambiguousRoleValidator = (control: AbstractControl): ValidationErrors | null => {
  // read the other control directly from form
  const name = this.fg?.get('name')?.value;
  const role = this.fg?.get('role')?.value; // same as control
  return name && role && name === role ? { unambiguousRole: true } : null;
};

name: [''],
role: ['', this.unambiguousRoleValidator],

The result looks like this

The only problem with this is that user needs to blur the Role field to validate again. The ugly way to fix it is watch changes on the first element, to update the second.

// form component
`<input crinput type="text" id="name" formControlName="name"
    (change)="checkRole()" />`

// ...

checkRole() {
  this.fg.get('role').updateValueAndValidity();
}

Form validation

Another way to catch cross-form validation is to validate the form itself. We still want the style to be attached to one control, but we want the trigger to be the form validation, instead of blur event validation. The simplest way is using CSS in combination to hasError

Going back to the above example, and changing the validator to be a form validator:

// form component

// add feedback somwhere, with a condition
template: `<div *ngIf="fg.hasError('unambiguousRole')" class="cr-form-feedback">An error here</div>`

this.fg = this.fb.group({
  //...
  name: ['', this.forbiddenNameValidator(/bob/i)],
  role: ['']

}, { validators: this.unambiguousRoleValidator });

Then in CSS, we just need to show it upon submission only (and add the colors and what not)

/* input.css */

.cr-form {
  .cr-form-feedback {
    display: none;
  }
  &.ng-submitted .cr-form-feedback {
    display: block;
  }
}

We can place that HTML element anywhere, if we place it inside a cr-input element, with an extra cr-feedback class, it would look like a normal contextual error.

<cr-input placeholder="Role" >
  <input crinput type="text" id="role" formControlName="role" [required]="true"  />
  <span *ngIf="fg.hasError('unambiguousRole')" class="cr-form-feedback cr-feedback">Name cannot match role or audiences will be confused.</span>
</cr-input>

Add a new property for cross field validation

We can now rewrite our input partial to cater for this with a new boolean property, let's call it invalidForm.

<cr-input placeholder="Role" error="Name cannot match role or audiences will be confused." [invalidForm]="fg.hasError('unambiguousRole')">
  <input crinput type="text" id="role" formControlName="role" [required]="true"  />
</cr-input>

In the library component

// input.partial

template: `
  // add to container compoennt
  <div class="{{ cssPrefix }}-field" [class.cr-invalid-form]="invalidForm">
    // and to feedback element
    <span class="cr-feedback" [class.cr-invalid-feedback]="invalidForm">{{ errorText }}</span>
  </div>
`,
@Input() invalidForm: boolean;

Now our css can accommodate the new cr-invalid-form, when the form is submitted, the cr-input should act as invalid because the invalidForm boolean is true when invalid.

/* input.css */

.ng-submitted {
  .cr-field {
    .cr-input.ng-invalid,
    /* add this selector */
    &.cr-invalid-form .cr-input {
      box-shadow: inset 0 0 0 1px var(--sh-red, #f31109);
      border-color: var(--sh-red, #f31109);
    }
    .cr-input.ng-invalid ~ .cr-feedback {
      display: block;
    }
    .cr-label:has(~ .cr-input.ng-invalid),
    /* and this selector */
    &.cr-invalid-form .cr-label {
      color: var(--sh-red, #f31109);
    }
  }
}
/* we can keep the .cr-form definiton for standalone feedback */

Changing the value of other fields no longer needs to be watched, as fg.hasError('unambiguousRole') is always up to date. Great.

Issue: Multiple error messages

The idea of having a custom error property is to overwrite the error messages in the component. But if there are multiple validations, the custom error will override them all. But we can bind the error message as follows:

[error]="fg.hasError('unambiguousRole') ? 'Name cannot match role or audiences will be confused.' : null"

If null, the required message takes over.

I personally have no problem with that, and I will not try to fix it to be a mutant. My simple user friendly solution is to change the message itself:

Required. And cannot match name to avoid confusion.

There. Problem solved.

Using the directive in other ways

Here is a scenario, a control of two fields, and the output result combined is what needs to be validated. Example: Month, and Year. Need to be in the future.

The idea is not to squeeze our control to handle that, but to have an output that follows the same design decisions. If we deal with them as separate fields, then it's just cross-form validation.

Ideally, the month and year controls, normal text controls, are wrapped inside a custom control that emits the value MMYY. Which is then assigned to a hidden input, that needs to be validated. This is easy and straight forward. Better than trying to squeeze in the validation in the non control. I like the fact that Angular turned validation to a simple custom function.

The only problem we will be facing is styling. Which we will be addressing later.

// form component

`<cr-input placeholder="Expiration" error="This is expired">
  <input type="hidden" crinput id="mmyy" pattern="[0-9]{4}" formControlName="mmyy" />
  // some component with MM and YY fields
  <cr-product-expiry (onValue)="expirationValue($event)"></cr-product-expiry>
</cr-input>`

//... in class
thisMonth: string = (new Date()).toISOString().substring(2, 7).replace('-', '');

futureValidator = (control: AbstractControl): ValidationErrors | null => {
  // if control MMYY in the future, return null
  const value = control.value;

  if (!value || +value > +this.thisMonth) {
    return null;
  }
  return {
    future: true
  };
};

expirationValue(value: { month: string, year: string; }) {
  // change form value to be mm then yy
  this.fg.get('mmyy').setValue(value.year + value.month);
}

// on init
this.fg = this.fb.group({
  //...
  mmyy: [null, this.futureValidator],
}

The result is looks like this. May be later we need to adapt the required asterisk for hidden fields.

The best experience

After years of working with different mindsets and different forms, I'd say the best experience in form validation is like this;

Do not validate first time, wait for first submission (unless it's an in place form, wait for blur)
Error messages, show all possible errors without breaking logic (Required, too large, or too small) but don't wait for a second input to show a different error.
Keep the error messages to the bare minimum, instead, depend on help text
Do not scroll up, toast

The last bit was a lesson I learnt the hard way. When there is a problem in form, toast that there are problems, then let user do their own scrolling up.

On submit, show your toast

submit() {
  if (this.fg.invalid) {
    this.toast.ShowError('INVALID_FORM');
  }
}

Want to create a toast control? Read about it in my Garage

Form types

Now that we validated the text input, let's move on to different types, and see what else we need to take care of. Besides the style. This should till next episode. 🥱

Did you know that Google is complicit in Gaza Genocide and Palestinian ethnic cleansing?

Resources

Alternative way to localize in Angular

Angular form validation directive - Sekrab Garage

Taming Angular forms. The component we created thus far is enough to make the form invalid if submitted, and show the “required” balloon when the field is invalid. Following is other built-in validations.The final result.... Posted in Angular, Design

garage.sekrab.com

Taming Angular Forms

Ayyash — Thu, 02 Jan 2025 11:38:00 +0000

Creating a form has always been a terrible task I keep till the end. And I usually just start with copying an existing form file. Today, I decided to do something about it. Here is a series to dig into Angular forms, in their simplest shape, and create reusable component to control validation.

I want to create a simple reusable solution for forms in Angular. A solution that is unobtrusive, and non-third-party reliant. The following is what I want to end up with:

Use native HTML input elements.
Validation rules should be kept to minimum
Keep the Angular form loose (do not reinvent the wheel)
Use attributes instead of Form builder (unobtrusive)
Keep form submission loose to allow as much flexibility
Minimum styling allowing full replacement.

The end result should look something like this:

In order to do that, we need to crack open the secrets of Angular forms. First, the HTML input basic form:

<input type="text" formControlName="name" [required]="true" />

The final solution can be found on StackBlitz

The series will cover the following topics:

Creating a component that relies on CSS only to display validation
Creating a validation directive to better control the error message
Listing the different input types and fine tune their validation
Putting together the most common validation functions, like Date, Password confirmation and Upload file validation

Opening the input box

Angular adds CSS classes and HTML attributes to the form field, upon interactions, as follows.

.ng-valid versus .ng-invalid reflects the validity at all times
.ng-pending used with asynchronous validation, between states
.ng-pristine versus .ng-dirty reflects whether the value changed, on keypress
.ng-untouched versus .ng-touched reflects the first state after blur, it will be touched after first blur
.ng-submitted is for the form element if it exists, after submission by firing the submit event

Angular mirrors native HTML classes, then disables it using novalidate, we will not enabled it because we don’t want to end up caring for two systems. Let’s dig in those classes. This is the simplest standalone form control:

// form page
@Component({
    // ...
  template: `<input type="text" [formControl]="valvet"  />`
})
export class FormComponent implements OnInit {
  valvet: FormControl;
  ngOnInit(): void {
    this.valvet = new FormControl('');
  }
}

Running, turns out the following

<input type="text" class="ng-untouched ng-pristine ng-valid" >

The flow is summarized as follows:

It begins with untouched and pristine
If blurred it becomes touched even if no value changed
If required is set, it starts with invalid, unless value is already set.
On keypress it receives dirty
Validity is updated whenever change occurs

The main thing to pay attention to: it becomes touched after first blur event, and not on focus.

Resetting using reset() returns everything to its initial state, except the value, it becomes empty.

Placing in a form element:

// form page
template: `
  <form [formGroup]="fg">
    <input type="text" formControlName="valvet" [required]="true"  />
    <button type="reset" (click)="reset()">Reset</button>
    <button type="submit">Submit</button> 
  </form>
   `
  // ...
  fg: FormGroup;

  ngOnInit(): void {
    this.fg = new FormGroup({
      valvet: new FormControl('')
    });
  }
  reset() {
    this.fg.reset();
  }

The form gets the same classes, and reflects the single input classes

/* Output */
<form novalidate="" class="ng-untouched ng-pristine ng-invalid">
  <input type="text" formcontrolname="valvet" class="ng-untouched ng-pristine ng-invalid" required>
  <button type="reset">Reset</button>
  <button type="submit" >Submit</button>
</form>

To continue with the flow:

It starts with untouched and pristine and valid
It reflects the state of at least one form field that is touched dirty or invalid
On submit button click, ng-submitted is added to the form classes.
Resetting does not take away the submitted state

Remember that by default the button type is submit, so we always need to be explicit about non submitting buttons. In this case, the reset button is of type reset

This is nice, we can control the validation style completely in CSS. The ideal behavior is: do not validate until submitted, there is nothing more annoying that validation nag.

Here is a quick example:

/* CSS to control the red border */
.cr-input {
  outline: 1px solid #ccc;
  border: 0;
}

/* when sourunded by ng-submitted */
.ng-submitted .cr-input.ng-invalid {
  outline: 1px solid red;
}

There might be times you want to handle it differently, by showing invalidity the minute it’s dirty.

/* a differnet way */
.cr-input {
  outline: 1px solid #ccc;
  border: 0;
}

/* when invalid and dirty */
.cr-input.ng-invalid.ng-dirty {
  outline: 1px solid red;
}

We can make an enhancement by removing the style on focus

/* garnish, on focus remove red border */
.cr-input:focus {
    outline: 1px solid #007bff;
}

We need to control the appearance of the required label, and the safest way is to wrap it with another element. The bare minimum of this new element is:

a label
an asterisk
a span with required text

The final result of the HTML should look like this

<!-- the targeted HTML -->
<div class="cr-field">
  <label class="cr-label" for="valvet">Valvet</label>
  <input type="text" id="valvet" class="cr-input" formControlName="valvet" [required]="true" />
  <span class="cr-required"></span>
  <span class="cr-feedback">Required</span>
</div>

The asterisk is a pseudo element. We can target the asterisk with the validity state

.cr-input ~ .cr-required {
  display: none;
  color: red;
  font-weight: bold;
  &:after {
      content: '*';
  }
}
.cr-input[required] ~ .cr-required {
  display: inline-block;
}

We can also target the parent-child relationship using the :has() operator. We will need that for the label, because we need to style the “previous sibling” according to state.

.cr-label {
  display: block;
  margin-block-end: 5px;
}
/* this is a new CSS feature */
.cr-label:has(~ .cr-input:focus-visible) {
  color: #007bff;
}

This looks nice. Last time I worked on this, I had to write a whole lot of code, now eliminated by two features:

:has() new selector
ng-submitted new state

Amazing!

Preparing for floating labels

One more pseudo class that can spice it up, is the :placeholder-shown selector. If the field is empty, the placeholder is showing. If field is focused, or the field is not empty, the placeholder is hidden. Let’s style this (this will come in handy when we create floating placeholders).

We don’t need the placeholder itself, because we will float in the label itself, later. So we make it transparent:

/* example styles to target placeholder */
.cr-input:placeholder-shown {
  outline: 1px solid green;
}
/* because we don't need the placholder */
.cr-input::placeholder {
  color: transparent;
}
.cr-label:has(~ .cr-input:placeholder-shown) {
  color: red;
}

But this means the placeholder value cannot be empty. We can place a “.” in it. Later we can automate this process when we create our component.

Finally the “required” feedback that appears when validated and form is submitted.

.cr-input ~ .cr-feedback {
  display: none;
  color: red;
  font-weight: bold;
}
.ng-submitted {
  .cr-input.ng-invalid {
    outline: 1px solid red;
  }
  .cr-input.ng-invalid ~ .cr-feedback {
    display: block;
  }
}

Nested styles are now native. Yippee!

The code can now be transferred into its own component. We probably need to add “id” for the label (naming it an id property is a bad choice, so we name it for). Let’s call it input.partial.ts. The native input field is content-projected.


// input.partial

@Component({
  selector: 'cr-input',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="cr-field">
      <label class="cr-label" for="{{for}}">{{ placeholder }}</label>
      <!-- content projection -->
      <ng-content></ng-content>
      <span class="cr-required">*</span>
      <span class="cr-feedback">Required</span>
    </div>
    `,
})

export class CrInputPartial implements AfterContentInit {

  @ContentChild('crinput', { static: true, read: ElementRef }) inputElement!: ElementRef;
  @Input() placeholder: string;

  for!: string;
  ngAfterContentInit() {
    // get the id from the native element
    this.for = this.inputElement.nativeElement.id;
    // assign the default placeholder as a placeholder attribute
    this.inputElement.nativeElement.setAttribute('placeholder', this.placeholder);
  }

}

In the consuming component (let’s call it formComponent):

<!-- formComponent html template -->
<cr-input placeholder="Valvet">
  <input #crinput type="text" id="valvet" class="cr-input" formControlName="valvet" [required]="true" />
</cr-input>

The #crinput is necessary, but later we will create a directive to take care of other things and replace it.

Do we keep the styles contained within the component, or do we let the outside world define it? I’m torn.

I usually prefer to keep it outside, so that each project has its own styling.
For the past 5 or so years, I rarely touched the CSS

So to stay true to both, let’s add the CSS in the component, but allow an override of the parent class for further fine tuning.

// input.partial
@Component({
  // ...
  styleUrl: 'input.css',
  // do not encapsulate
  encapsulation: ViewEncapsulation.None,
  // added cssPrefix
  template: `
    <div class="{{ cssPrefix }}-field">
      <label class="cr-label" for="{{for}}">{{ placeholder }}</label>
      <ng-content></ng-content>
      <span class="cr-required">*</span>
      <span class="cr-feedback">Required</span>
    </div>
    `,
})
export class CrInputPartial implements AfterContentInit {
    //...
    // make the cssPrefix an optional input
  @Input() cssPrefix: string = 'cr';

  ngAfterContentInit() {
      // push the class to the input
    this.inputElement?.nativeElement.classList.add(`cr-input`);
  }
}

The CSS is going to be a floating labels style, we will use CSS vars with a fallback, and we will not include the width, because width is defined in the consumer. Every project has its own story.

The CSS:( --sh stands for shut)

/* input.css */

.cr-field {
  position: relative;
  display: block;
  margin-block-end: var(--sh-doublespace, 3.2rem);
  margin-block-start: var(--sh-halfspace, 0.8rem);
  .cr-input {
    border: 1px solid var(--sh-grey, #999999);
    border-radius: var(--sh-radius, 3px);
    appearance: none; /* I don't think this is necessary */
    outline: none;
    padding: var(--sh-halfspace, 0.8rem);
    box-shadow: 0 2px 5px 0 var(--sh-grey-light, #f3f3f3cc);

    background-color: var(--sh-white, #ffffff);
    caret-color: var(--sh-linkcolor, #0c00b4);
    &:focus-visible {
        outline: none;
        border-color: var(--sh-linkcolor, #0c00b4);
        box-shadow: 0 0 0 1px var(--sh-linkcolor, #0c00b4);
    }
    /* nice to have, hide asterisk when input is focused */
    &:focus-visible ~ .cr-required {
        display: none!important;
    }
    &::placeholder {
      color: transparent!important;
    }

  }
  .cr-input ~ .cr-required {
    display: none;
    position: absolute;
    inset-inline-end: var(--sh-halfspace, 0.8rem);
    inset-block-start: 0;
    z-index: 2;
    &:after {
        display: block;
        content: '*';
        font-size: 1.6rem;
        font-weight: var(--sh-font-weight-bold, 700);
        line-height: 1.5;
        color: var(--sh-red, #f31109);
    }

  }
  .cr-input[required] ~ .cr-required {
    display: inline-block;
  }

  .cr-feedback {
    background-color: var(--sh-red, #f31109);
    color: var(--sh-white, #ffffff);
    margin-inline-start: 1rem;
    margin-block-start: calc(-1 * var(--sh-halfspace, 1.6rem));
    width: fit-content;
    float: inline-start;
    z-index: 100;
    position: relative;
    border-radius: var(--sh-radius, 3px);
    padding-inline: var(--sh-halfspace, 0.8rem);
    padding-block: calc(var(--sh-halfspace, 0.8rem) / 2);
    white-space: nowrap;
    display: none;
    font-size: 85%;
  }

  /* floating label */
  .cr-label {
    position: absolute;
    inset-block-start: var(--sh-halfspace, 0.8rem);
    inset-inline-start: 9px;
    padding: 0 3px;
    color: var(--sh-text-light, #959595);
    cursor: auto;
    transform-origin: left;
    transition: transform 0.3s;
    transform: translateY(-100%) scale(0.8);
    /* a touch to hide the border behind the floating label */
    background-image: linear-gradient(0deg, var(--sh-white, #ffffff) 62%, transparent 62%);
  }
  /* when input is empty */
  .cr-label:has(~ .cr-input:placeholder-shown) {
    transform: none;
  }
  /* when input is focused */
  .cr-label:has(~ .cr-input:focus-visible) {
    transform: translateY(-100%) scale(0.8);
  }
}

/* when sourunded by ng-submitted */
.ng-submitted {
  .cr-field {

    .cr-input.ng-invalid {
      box-shadow: inset 0 0 0 1px var(--sh-red, #f31109);
      border-color: var(--sh-red, #f31109);
    }
    .cr-input.ng-invalid ~ .cr-feedback {
      display: block;
    }
    .cr-label:has(~ .cr-input.ng-invalid) {
      color: var(--sh-red, #f31109);
    }
  }
}

The form itself is simple:

this.fg = this.fb.group({
  valvet: [''],
  mars: ['']
});

The initial state of this component is coming together, find it on StackBlitz.

Next.

Validation

We now know how to make it required, the above was enough to make the form invalid if submitted, and show the required balloon. Let’s see other built in validations. Next episode. 🥱

Did you see how useless touching an input was?

Resources

Using CSS to validate Angular reactive form - Sekrab Garage

Taming Angular Forms. I want to create a simple reusable solution for forms in Angular. A solution that is unobtrusive, and non-third-party reliant. The following is what I want to end up with:<ul><li>Use native HTML input.... Posted in Angular, Design

garage.sekrab.com

Upgrading to Angular version 19

Ayyash — Mon, 23 Dec 2024 10:00:00 +0000

There are two ways to update, using ng update directly, or creating a new application after updating the global @angular/cli. They produce slightly different results. Mainly the builder used. The new changes touch the angular.json more than anything else. Some of the new options are not yet documented.

Updating to Angular 19

The resulting sever code can be found on StackBlitz

Optionally start with npm install -g @angular/cli to update the global builder to the new version.

Use ng update @angular/core@19 @angular/cli@19. Or create a new application with ng new appname --ssr . The difference is the @angular/builder, the ng update command prompts you with this extra option:

Select the migrations that you'd like to run 
❯◉ [use-application-builder] Migrate application projects to the new build system.
(<https://angular.dev/tools/cli/build-system-migration>)

The new builder does not have the server separate builder. The same ng build will be responsible for building the client side, and the server side.

Another option prompted is updating the APP_INITIALIZER to the new provideAppInitializer.

Current project changes

This will remove all standalone: true because it is the default in the new version.
APP_INITLAIZER is deprecated (see below).
The builder @angular-devkit/build-angular:server is deprecated, let’s not use it
@angular-devkit/build-angular has changed to @angular/build
Server side rendering implementation changed (we’ll dig deeper into this one).
the tsconfig.app.json now adds the server related files.
Watch out for deleted files, it may not be a great idea.

The documentation of the new CLI options, and how to transfer to the new builder can be found on the official Angular website. But not everything is well documented.

Updating APP_INITIALIZER

This provider is now deprecated. The new version is a function, so:

// old
  {
    provide: APP_INITIALIZER,
    useFactory: configFactory,
    multi: true,
    deps: [ConfigService]
  },

Becomes (Angular docs for provideAppInitializer):

// new
provideAppInitializer(() => {
  const initializerFn = (configFactory)(inject(ConfigService));
  return initializerFn();
}),

The new provider expects a function of type **EnvironmentProviders .** The above configFactory was a function that expected ConfigService to be injected as a dependency. That was the auto generated code from the following:

// the configFactory, and the ConfigService
export const configFactory = (config: ConfigService) => () => {
  return config.loadAppConfig();
};

@Injectable({
  providedIn: 'root'
})
export class ConfigService {
    // ...
    loadAppConfig(): Observable<boolean> {
        // return an http call to get some configuration json
        return this.http.get(this._getUrl).pipe(
            map((response) => {
                return true;
            })
        );
    }
}

But wait. We can write this better. Since we have injection context, we’ll just inject the ConfigService directly.

// a better way
export const configFactory =  () => {
  // inject, and return the Observerable function
  const config = inject(ConfigService);
  return config.loadAppConfig();
};

// then just use directly
provideAppInitializer(configFactory),

This works as expected.

Updating ENVIRONMENT_INITIALIZER

The other deprecated token is ENVIRONMENT_INITIALIZER. Read Angular documentation of the alternative (provideEnvironmentInitializer). Here is an example of before and after of the simplest provider.

// before
  {
    provide: ENVIRONMENT_INITIALIZER,
    multi: true,
    useValue() {
      console.log('environment');
    },
  }

Becomes

provideEnvironmentInitializer(() => {
  console.log('environment');
})

In a more complicated scenario, the changes are just as simple as in the APP_INITIALIZER. Here is an example of a provider that detects scroll events of the router.

// before, route provider:
// factory
const appFactory = (router: Router) => () => {
    // example
  router.events.pipe(
    filter(event => event instanceof Scroll)
  ).subscribe({
    next: (e: Scroll) => {
      // do something with scroll
      console.log(e.position);
    }
  });
};

// provided:
{
  provide: ENVIRONMENT_INITIALIZER,
  multi: true,
  useFactory: appFactory,
  deps: [Router]
}

This becomes:

// new, reduced appFactory with simple inject
const appFactory = ()  => {
  const router: Router = inject(Router);

  router.events.pipe(
    filter(event => event instanceof Scroll)
  ).subscribe({
    next: (e: Scroll) => {
      // do something with scroll
      console.log(e.position);
    }
  });
};

// then simply use it:
provideEnvironmentInitializer(appFactory)

Server side rendering, generation, and hydration

The documentation is thorough about the three options: rendering (produces a NodeJs version to be hosted using Express), generation (produces HTML static files to be hosted by an HTML host), and hydration (produces both and allows prerendering for selective routes).

What we want to do here, is move our current application as is, this isn’t the place for new options. So here is what we produced for our SSR custom solution.

The current server builder @angular-devkit/build-angular:server is no longer in use, thus the old way of creating a single configuration won’t work.

Note: current Angular documentation covers this but not everything

The following configuration, changed:

// angular.json, was
"builder": "@angular-devkit/build-angular:browser",
"outputPath": "../dist/public/",
"resourcesOutputPath": "assets/",
"main": "src/main.ts",

Becomes

// angular.json, is
"builder": "@angular/build:application", // changed builder
"outputPath": {
  "base": "../dist/public/", // example
  "browser": "browser", // sub folder for browser
  "media": "assets", // rename to assets to keep everything the same
  "server": "server" // sub folder to server, can be empty
},
"browser": "src/main.ts", // instead of "main"
"server": "src/main.server.ts", // new... to explain
"ssr": {
  "entry": "server.ts" // new
},
"prerender": false, // not needed

The tsconfig.app.json now includes the new server files

// tsconfig.app.json
"files": [
  "src/main.ts",
  "src/main.server.ts",
  "src/server.ts"
],

OutputPath

First, the outputPath. It’s now specific to generate the following folder structure upon ng build

Here is a link to the official documentation of the outputPath.

|- dist
|----public
|-------browser
|---------assets
|-------server

A single build creates both NodeJs and client-side. This is sort of a bummer, considering I have always separated them. Let’s try to get as close as possible to a working example.

Full client-side only

The config to create a similar output as before is as follows

// angular.json
"architect": {
    "build": {
        //...
        "configurations": {
            "production": {
                "outputPath": {
                    "base": "dist",
                    "browser": "", // reduce to keep everything on root
                    "media": "assets"
                },
                "index": "src/index.html",
                "browser": "src/main.ts",
            }
        }
  }
}

This will create an output that has index.html on the root, and the assets in their assets folder. Pretty straight forward.

Server side rendered

To create a folder with browser, and server subfolders, no prerendering, and simply using the example out of the box, we need to add server entry, then another ssr entry.

Angular documentation

"outputPath": {
  "base": "ssr",
  "browser": "browser", // cannot be empty here
  "media": "assets",
  "server": "server" // can be empty
},
"index": "src/index.html",
"browser": "src/main.ts",
// The full path for the server entry point to the application, relative to the current workspace.
"server": "src/main.server.ts", 
// if "entry" is used, it should point to the Express server that imports the bootstrapped application from the main.server.ts
"ssr": true,

The main.server.ts must have the exported bootstrapped application. ssr has to be true.

The generated output contains the following

|-browser/
|--main-xxxxx.js
|--index.csr.html
|-server/
|--main.server.mjs
|--index.server.html
|--assets-chunks/

This does not produce a server, you need to write your own server, and then map those folders to the expected routes. But we need the CommonEngine at least.

A note about the CommonEngine

The CommonEngine is the currently working NodeJs engine, but there is another one AngularNodeAppEngine that is still in developer preview.

SSR entry server

The configuration is slightly different, and it includes the NodeJs CommonEngine server.

"outputPath": {
  "base": "ssr",
  "browser": "browser",
  "media": "assets",
  "server": "server"
},
"index": "src/index.html",
"browser": "src/main.ts",
"server": "src/main.server.ts", // has the bootstrapped app
"ssr": {
    // The server entry-point that when executed will spawn the web server.
    // this has the CommonEngine
    "entry": "src/server.ts"
},

The output looks like this

|-browser/
|--main-xxxxx.js
|--index.csr.html
|-server/
|--main.server.mjs
|--index.server.html
|--assets-chunks/
|--server.mjs

The server.mjs contains the Express listener so we can node server.mjs to start the server. (see the Angular documentation link above.)

Running the server with JavaScript disabled works. The browser folder is necessary only for running Angular in browser, but the site works fine without it (I have not tested with multiple routes).

Removing browser/index.csr.html actually did nothing! Hmm. Maybe the file is needed for generating prerendered files.

Isolating the server

We begin with exporting the CommonEngine in server.ts without a listener, and create our own Express listener. Using the same code we generated in the last post, and since the application bootstrapper is in the same file, here is the configuration to start with:

// angular.json
"ssr": {
  "outputPath": {
    "base": "../garage.host/ssr", // a new folder in host
    "server": "", // simpler
    "browser": "browser",
    "media": "assets"
  },
  // this has the application bootstrapper as well
  "server": "server.ts",
  "ssr": true
}

The changes we need to make are:

add server.ts to the list of files in tsconfig.app.json.
remove import zone.js from our server file
change the CommonEngine source from @angular/ssr to @angular/ssr/node

// server.ts in our new server
// chagen to "node" sub folder
import { CommonEngine, CommonEngineRenderOptions } from '@angular/ssr/node';
// remove: import 'zone.js';

Then ng build --configuration=ssr

The first error I receive is

[ERROR] No matching export in server.ts for import "default”

Obviously, the Angular builder expects something specific. So let’s export a default bootstrap application from our server.

// in server.ts, lets have a default export, this may be good enough
const _app = () => bootstrapApplication(AppComponent, {
  providers: [
    provideServerRendering(),
    ...appProviders
  ]}
);
// make it the default
export default _app;

The output contains two folders, and main.server.mjs in the root folder. It has crExpressEgine that we created. (Did you catch the typo in crExpressEgine? Yeah well, it’s too late to fix it.)

Our Express can still import it and use it as an engine. It would look like this:


// our server.js in another folder

// the ssr engine comes from the outout sever/main.server.mjs
const ssr = require('./ssr/main.server.mjs');
const app = express();

// the dist folder is the browser
const distFolder = join(process.cwd(), './ssr/browser');
// use the engine we exported
app.engine('html', ssr.crExpressEgine);
app.set('view engine', 'html');
app.set('views', distFolder);

// ...
app.get('*'), (req, res) => {
  const { protocol, originalUrl, headers } = req;

  // serve the main index file generated in browser
  res.render(`index.html`, {
    // set the URL here
    url: `${protocol}://${headers.host}${originalUrl}`,
    // pass providers here, if any, for example "serverUrl"
    providers: [
      {
        provide: 'serverUrl',
        useValue: res.locals.serverUrl // something already saved
      }
    ],
    // we can also pass other options
    // document: use this to generate different DOM content
    // turn off inlinecriticalcss
    // inlineCriticalCss: false 
  });
});

So the only change is how we use the root and the browser folders. And of course, the EJS cannot be “required.” We can build the server in typescript. Or turn it into an es-script. We start with package.json

// package.json on root folder of the express server
{
    "type" :"module"
}

Then we change all require statements to imports

// new esscript server
import express from 'express';
import { join } from 'path';

import { crExpressEgine } from './ssr/server/main.server.mjs';
const app = express();

const distFolder = join(process.cwd(), './ssr/browser');
app.engine('html', crExpressEgine);
app.set('view engine', 'html');
app.set('views', distFolder);

app.use( express.static(distFolder));

app.get('*'), (req, res) => {
    // This is the browser index, so if you have index.xxx.html use it
    res.render('index.html', {
    // ...
    });

});

Running the server in Node (node server), and browsing with JavaScript disabled, it looks like it’s working.

Request and Response tokens

Previously we needed to recreate the Request and Response tokens to continue to use them. In Angular 19, tokens are back. Well. Not so fast. If you see in the server.ts an implementation of CommonEngine it will not have the Request token implemented. But AngularNodeAppEngine I can see the tokens provided:

// Angular source code for the new Enginer: AngularNodeAppEngine
if (renderMode === RenderMode.Server) {
  // Configure platform providers for request and response only for SSR.
  platformProviders.push(
    {
      provide: REQUEST,
      useValue: request,
    },
    {
      provide: REQUEST_CONTEXT,
      useValue: requestContext,
    },
    {
      provide: RESPONSE_INIT,
      useValue: responseInit,
    },
  );
}

So we need to change the RenderMode to Server.

// in the app.routes.server.ts, the out of the box file
export const serverRoutes: ServerRoute[] = [
  {
    path: '**',
    // this needs to be Server to get access to tokens
    renderMode: RenderMode.Server
  }
];

The AngularNodeAppEngine is in developer preview mode. So we don’t have to use it. We’ll just continue to provide the tokens as we did before. Personally I don’t like to have to configure the Server routes to get access to the server REQUEST.

Official documentation of this engine.

The token that I previously created, compared to the officially new token in Angular 19:

// our REQUEST token, very simple
export const REQUEST: InjectionToken<any> = new InjectionToken('REQUEST Token');

// official Angular 19 token
export const REQUEST = new InjectionToken<Request | null>('REQUEST', {
  providedIn: 'platform',
  factory: () => null,
});

That’s garnish. The other two tokens are: REQUEST_CONTEXT and RESPONSE_INIT. Meh!

the StackBlitz project includes the custom tokens.

Bonus

The hiccup in all of this is that if you do your own prerendering like I do, you would want the browser folder to be served alone. But since the new outputPath does not allow that, so you’d just need to map your routes to this inner folder. For example, in firebase config, it would look like this

// firebase.json
{
    "hosting": [
        {
            "target": "web",
            // the inner most browser folder
            "public": "ssr/browser",
            "rewrites": [
                {
                    "source": "/",
                    "destination": "/index.html"
                }
            ]
        },
    ]
}

The prerender script (if you have one like mine) should write inside the browser folder.

Conclusion

With the latest update in Angular 19 SSR builder, there are few changes to make on current projects, which the following specs should be met:

Uses an isolated Express server that serves the site independently. Thus the generated server.ts which contains a listener needs to be adapted to remove the listener
Uses an Express Node server, this may need to update to ES Module.
Localization is done natively, single build that serves multiple languages, thus the server and the index.html are created in a separate build (Not covered in this article).
I have come to realize that prerendering isn’t really meaningful unless you have dynamic data to generate. An AppShell is something I also never made use of. Thus the partial hydration to me is a buzz word.
Never buy into occupation.

Replacing Angular Universal with SSR version 17.0

Ayyash — Tue, 23 Jan 2024 10:00:00 +0000

Angular has adopted Universal and made it a kid of its own! Today I will rewrite some old code we used to isolated express server as we documented before with the most extreme version of serving the same build for multiple languages from Express, we are also using a standalone version as we covered recently.

Let's dig.

Find GitHub branch of cricketere with server implementation

Setup

We need to first install SSR package and remove any reference to Angular Universal. (Assuming we have upgraded to Angular 17.0)

npm install @angular/ssr

npm uninstall @nguniversal/common @nguniversal/express-engine @nguniversal/builders

Using ng add @angular/ssr rewrites the server.ts and it claims to add a config file somewhere. Yeah, nope!

In our last attempt for a skimmed down, standalone server.ts, it looked like this

// the last server.ts
import { ngExpressEngine } from '@nguniversal/express-engine';
import 'zone.js/dist/zone-node';
// ...
const _app = () => bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(ServerModule),
    // providers: providers array...
  ],
});

// export the bare minimum, let nodejs take care of everything else
export const AppEngine = ngExpressEngine({
  bootstrap: _app
});

Now the ngExpressEngine is gone. Here are three sources to dig into to see if we can create our own skimmed down engine.

ngExpressEngine source code
The new ssr CommonEngine source code
Angular documentation of the ssr CommonEngine
Express custom template engine documentation

The original Universal Express Engine received options, created the return function, and used the CommonEngine to render. We can recreate a template engine with much less abstraction in our server.ts. Here is the outcome.

Changes

First, remember to import zone.js directly instead of the deep path zone.js/dist/zone-node
The CommonEngine instance can be created directly with at least bootstrap property set
Export the express engine function
Get rid of a lot of abstractions
The URL property cannot be set in Angular, it better be set in Express route.
Use provideServerRendering, instead of importProvidersFrom

The new server.ts now looks like this:

// server.ts
// remove nguniversal references
// import { ngExpressEngine } from '@nguniversal/express-engine';

// change import from deep to shallow:
import 'zone.js';

// add this
import { CommonEngine, CommonEngineRenderOptions } from '@angular/ssr';

// the standalone bootstrapper
const _app = () => bootstrapApplication(AppComponent, {
  providers: [
    // this new line from @angular/platform-server
    provideServerRendering(),
    // provide what we need for our multilingual build
    // ... providers array
  ],
});

// create engine from CommonEngine, pass the bootstrap property
const engine = new CommonEngine({ bootstrap: _app });

// custom express template angine, lets call it cr for cricket
export function crExpressEgine(
  filePath: string,
  options: object,
  callback: (err?: Error | null, html?: string) => void,
) {
  try {
    // grab the options passed in our Express server
    const renderOptions = { ...options } as CommonEngineRenderOptions;

    // set documentFilePath to the first arugment of render
    renderOptions.documentFilePath = filePath;

    // the options contain settings.view value
    // which is set by app.set('views', './client') in Express server
    // assign it to publicPath
    renderOptions.publicPath = (options as any).settings?.views;

    // then render
    engine
      .render(renderOptions)
      .then((html) => callback(null, html))
      .catch(callback);
  } catch (err) {
    callback(err);
  }
};

Our Express route code, which is where the main call for all URLs are caught and processed:

// routes.js
// this won't change (it's defined by outputPath of angular.json server build)
const ssr = require('./ng/main');

// app is an express app created earlier
module.exports = function (app, config) {
  // we change the engine to crExpressEngine
  app.engine('html', ssr.crExpressEgine);
  app.set('view engine', 'html');
  // here we set the views for publicPath
  app.set('views',  './client');

  app.get('*'), (req, res) => {
    const { protocol, originalUrl, headers } = req;

    // serve the main index file
    res.render(`client/index.html`, {
      // set the URL here
      url: `${protocol}://${headers.host}${originalUrl}`,
      // pass providers here, if any, for example "serverUrl"
      providers: [
        {
          provide: 'serverUrl',
          useValue: res.locals.serverUrl // something already saved
        }
      ],
      // we can also pass other options
      // document: use this to generate different DOM content
      // turn off inlinecriticalcss
      // inlineCriticalCss: false
    });
  });
};

Built, Express server run, and tested. Works as expected.

A note about the URL, in a previous article we ran into an issue with reverse proxy, and had to set the the URL from a different source, as follows:

// fixing URL with reverse proxy
let proto = req.protocol;
if (req.headers && req.headers['x-forwarded-proto']) {
    // use this instead
    proto = req.headers['x-forwarded-proto'].toString();
}
// also, always use req.get('host')
const url = `${proto}://${req.get('host')}`;

This is better than the one documented in Angular.

Passing request and response

We cannot provide req and res as we did before, we used to depend on REQUEST token from nguniversal library. But we don't need to most of the time, we can inject the values we want from request directly into the express providers array. Here are a couple of examples: a json config file from the server, and the server URL:

// routes.js
//...
res.render(...,
  // ... provide a config.json added in express
  providers: [
    {
      provide: 'localConfig',
      useValue: localConfig // some require('../config.json')
    },
    {
      provide: 'serverUrl',
      useValue: `${req.protocol}://${req.headers.host}`;
    }
  ]
});

Then when needed, simply inject directly

// some service in Angular
constructor(
  // inject from server
  @Optional() @Inject('localConfig') private localConfig: any,
  @Optional() @Inject('serverUrl') private serverUrl: string
)

If however we are using a standalone function that has no constructor, like the Http interceptor function, and we need to use inject, it's a bit more troublesome. (Why Angular?!). There are a couple of ways.

Getting from Injector

The first way is not documented, and it uses a function marked as deprecated, it has been marked for quite a while, but it is still being used under the hood. That's how I found it, by tracing my steps back to the source. Injecting the Injector itself to get whatever is in it.

// in a standalone function like http interceptor function
export const ProjectHttpInterceptorFn: HttpInterceptorFn =
(req: HttpRequest<any>, next: HttpHandlerFn) => {

  // Injector and inject from '@angular/core';
  // this is a depricated
  const serverUrl = inject(Injector).get('serverUrl', null);
  // use serverUrl for something like:
  let url = req.url;
  if (serverUrl) {
    url = `${serverUrl}/${req.url}`;
  }
  // ...
}

This is marked as deprecated.

Re-creating injection tokens

Looking at how Angular Universal Express Engine provided request and response, we get a hint of how we should do it the proper way.

We will follow the same line of thought, but let's get rid of the extra typing to keep it simple, to add Request, Response and our serverUrl. The steps we need to go through:

Curse Angular
Angular: define a new injection token
Angular consumer: inject optionally (dependency injection)
Angular server file: expose new attributes for the render function, that maps to a static providers
Angular server file: create the providers function from incoming attributes
Express: pass the values in the new exposed attributes.
Make peace with Angular.

In a new file, token.ts inside our app, we'll define the injection tokens:

// app/token
// new tokens, we can import Request and Response from 'express' for better typing
export const SERVER_URL: InjectionToken<string> = new InjectionToken('description of token');

export const REQUEST: InjectionToken<any> = new InjectionToken('REQUEST Token');
export const RESPONSE: InjectionToken<any> = new InjectionToken('RESPONSE Token');

Then in a consumer, like the Http interceptor function, directly inject and use.

// http interceptor function
export const LocalInterceptorFn: HttpInterceptorFn = (req: HttpRequest<any>, next: HttpHandlerFn) => {
  // make it optional so that it doesn't break in browser
  const serverUrl = inject(SERVER_URL, {optional: true});
  const req = inject(REQUEST, {optional: true});
  //... use it
}

In our server.ts we create the provider body for our new optional tokens, and we append it to the list of providers of the options attribute. The value of these tokens, will be passed with renderOptions list. Like this:

// server.ts
// rewrite by passing the new options
export function crExpressEgine(
  //...
) {
  try {
    // we can extend the type to a new type here with extra attributes
    // but not today
    const renderOptions = { ...options } as CommonEngineRenderOptions;

    // add new providers for our tokens
    renderOptions.providers = [
      ...renderOptions.providers,
      {
        // our token
        provide: SERVER_URL,
        // new Express attribute
        useValue: renderOptions['serverUrlPath']
      },
      {
        provide: REQUEST,
        useValue: renderOptions['serverReq']
      },
      {
        provide: RESPONSE,
        useValue: renderOptions['serverRes']
      }
    ];
  // ... render
  }
};

Finally, in the Express route, we just pass the req and res and serverUrlpath in render

// routes.js
app.get('...', (req, res) => {
  res.render(`../index/index.${res.locals.lang}.url.html`, {
    // add req, and res directly
    serverReq: req,
    serverRes: res,
    serverUrlPath: res.locals.serverUrl
    // ...
  });
});

Note, I change the names of properties on purpose not to get myself confused about which refers to which, it's a good habit.

Now we make peace. It's unfortunate there isn't an easier way to collect the providers by string! Angular? Why?

Merging providers

In order not to repeat ourselves between the client and server apps, we need to merge the providers into one. Angular provides a function out of the box for that purpose: mergeApplicationConfig (Find it here). Here is where we create a new config file for the providers list:

// in a new app.config
// in client app, export the config:
export const appConfig: ApplicationConfig = {
  providers: [
    // pass client providers, like LOCAL_ID, Interceptors, routers...
    ...CoreProviders
  ]
}

// in browser main.ts
bootstrapApplication(AppComponent, appConfig);

// in server.ts
// create extra providers and merge
const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering()
  ]
};

const _app = () => bootstrapApplication(AppComponent,
  mergeApplicationConfig(appConfig, serverConfig)
);

ApplicationConfig is nothing but a providers array, so I am not sure what the point is! I simply export the array, and expand it. Like this:

// app.config
// my preferred, less posh way
export const appProviders = [
  // ...
];

// main.ts
bootstrapApplication(AppComponent, {providers: appProviders});

// server.ts
const _app = () => bootstrapApplication(AppComponent,
  { providers: [...appProviders, provideServerRendering()] }
);

Providing Http Cache

The transfer cache last time I checked was automatically setup and used. In this version, I did not get my API to work on the server. Something missing. Sleeves rolled up.

The withHttpTransferCacheOptions is a hydration feature. Hmmm!

Partial Hydration

The new addition is partial hydration. Let's add the provideClientHydration to the main bootstrapper: the app.config list of providers, that will be merged into server.ts (it must be added to browser as well.)

// app.config
export const appProviders = [
  // ...
  provideClientHydration(),
];

Building, running in server, and the Http request is cached. It is a GET request, and there are no extra headers sent. So the default settings are good enough. There was no need to add withHttpTransferCacheOptions. Great.

So this is it. I tried innerHTML manipulation and had no errors. I also updated Sekrab Garage website to use partial hydration and I can see the difference. The page transition from static HTML to client side was flickery. Now the hydration is smooth.

Prerendering

The last bit to fix is our prerender builder. The source code of devkit is here.

The following lines are the core difference:

// these lines in the old nguniversal
const { ɵInlineCriticalCssProcessor: InlineCriticalCssProcessor } = await loadEsmModule<
    typeof import('@nguniversal/common/tools')
  >('@nguniversal/common/tools');

// new line in angular/rss
const { InlineCriticalCssProcessor } = await import(
  '../../utils/index-file/inline-critical-css'
);

Unfortunately we don't have access to that file (inline-critical-css). It is never exposed. Are we stuck? May be. The other solution is to bring it home (I don't like this). I am demoralized. I'll have to let go of my Angular builder, and rely on my prerender routes via express server. Which still works, no changes needed except the render attributes, as shown above.

So there you go, thank you for reading through this, did you make peace with Angular today? 🔻

RESOURCES

Replacing Angular Universal with SSR version 17.0 - Sekrab Garage

Angular SSR Update. Angular has adopted Universal and made it a kid of its own! Today I will rewrite some old code we used to isolated express server as we documented before with the most extreme version of serving th.... Posted in Angular

garage.sekrab.com

III - Firebase For Authentication only in Angular

Ayyash — Tue, 16 Jan 2024 10:00:00 +0000

The middle ground is to use Firebase Auth, for authentication, and use our own API for user management.

Find the project on Github.

Express API routes

The idea of having two servers, one for authentication and one for profiling is to deal with the profile server (our API) as a normal data source, with authentication required. The authentication server is expected to send in an access token, which is verified first, before it moves down the pipe of creating and editing user profile. So after signing in and signing up with password, or after signing in with Google, we need to send the token to our Express server to create the user, fetch user, or patch user.

// server/routes
router.post('/auth/login', function (req, res) {
  // if id does not exist create user, else update user
  const payload = req.body;
  const token = payload.token;
  // we need to first verify token
  sdk.auth().verifyIdToken(token).then(function (decodedToken) {
    // then find user by id
    const id = decodedToken.uid;
    // find profile in db, example
    const profile = {...};

    // if user does not exist, create one
    if (!profile) {
      // save new user to db then return
      // we don't have bloodType just yet
      const _newuser = {
        id: decodedToken.uid,
        picture: decodedToken.picture,
        // use the decodeToken for now
        email: decodedToken.email,
        // some hard coded attributes
        admin: true,
        // this flag is important
        newUser: true};
      // save _newuser in db here, then return
      // ...
      res.json(_newuser);
    } else {
      // return existing user with full profile, including bloodtype
      // watch out for client-side gap, bloodType may still not exist
      res.json(profile);
    }

  }).catch(function (error) {
    // 401
  });
});

// update logged in user
router.patch('/user', function(req, res) {
  // get from middleware
  const user = res.locals.user;

  if (user) {
    // update user in db with body
    const payload = req.body;
    let profile = {...user};
    profile.bloodType = payload.bloodType;
    // switch off newUser
    profile.newUser = false;
    // save to db
    // ...
    // update locals
    res.locals.user = profile;

    // return profile
    res.json(profile);
  } else {
     res.status(401).json({
      message: 'Access denied',
      code: 'ACCESS_DENIED'
    });
  }
});

As you can see I have saved the newUser flag in our server, because it is crucial to close a UI gap, we'll cover later.

// services/auth.service
// login changed, we'll map to IAuthInfo later
Login(email: string, password: string): Observable<IAuthInfo> {
  const res = () => signInWithEmailAndPassword(this.auth, email, password);
  return defer(res).pipe(
    // get the token to force a fresh one
    switchMap(auth => auth.user.getIdToken()),
    // login user in our API
    switchMap(token => this.LoginUser(token))
  );
}

LoginUser(token: string): Observable<IAuthInfo> {
  return this.http.post('/auth/login', { token });
  // we need to later save into state
}

Sign up with password would call the first route, then request the bloodType from the user, then call the PATCH /user next.

// services/auth.service
// sign up changed
SingUp(email: string, password: string, custom: any): Observable<IAuthInfo> {
  // here send a sign up request, with extra params
  const res = () =>
    createUserWithEmailAndPassword(this.auth, email, password);

  return defer(res).pipe(
    // first new token
    switchMap(auth => auth.user.getIdToken()),
    // log user in and request extra information
    switchMap(token => this.LoginUser(token)),
    // then patch
    switchMap(_ => this.UpdateUser(custom)
  );
}

UpdateUser(custom: any): Observable<IAuthInfo> {
  return this.http.patch('/user', custom).pipe(
    // we need to update state again here
  );
}

In our components so far nothing has changed. But we can do better. In a minute. First, let's see what changed on Sign in with Google.

Remember that we faced an issue with null tokens before, so here we getIdToken before any action to API.

Sign in with Google

In the previous episode we depended on the Firebase service to tell us whether the user is new or not using getAdditonalUserInfo, before we proceeded to show the sign up form. Now we need to log the user in our API server first. Our API server can take on the job and check if uid already exists, and return newUser from our data source. Initially the service call looks like this

// serivces/auth.service

// Login by Google initially:
LoginGoogle(): Observable<IAuthInfo> {
  const provider = new GoogleAuthProvider();
  const res = () => signInWithPopup(this.auth, provider);

  return defer(res).pipe(
    switchMap(auth => auth.user.getIdToken()),
    // call our API and check for uid
    switchMap(token => this.LoginUser(token))
  );
}

We can use the IAuthInfo model to check if user is new (remember the /auth/login returns newUser flag).

// components/public/login.component

// login with Google
loginGoogle() {
  this.authService.LoginGoogle()
  .subscribe({
    next: (user) => {
      // read newUser from our API
      if (!user.newUser) {
        this.router.navigateByUrl('/private/dashboard');
      } else {
        // show the sign up field (somehow)
        this.showMeForm = true;
      }
    },
  });
}
// finish sign up by google
update() {
  // grab form bloodType, example: B+
  this.authService.UpdateUser({ bloodType: 'B+' }).subscribe({
    next: (user) => this.router.navigateByUrl('/private/dashboard');
  });
}

If user is new, after submitting and calling update we proceed normally to call UpdateUser({bloodType}) to PATCH user.

The new user flag

The first thing we need to fix is this gap between Login and Sign Up, if user does not finish sign up and comes back later to try with the same Google email, Firebase will return an existing user. But that user never provided their bloodType. To fix that, we need to keep track of the newUser flag. The flag is turned off only when user finishes the sign up and provide bloodType. Which is in the PATCH /user route.

This is one of the two issues I promised we'd fix in the previous episode.

Request Email

The second issue to fix is the email. If you do not need an email in your application this should be fine. But if you, like the rest of us, would like to annoy your customers with endless propaganda emails, then you need the email. First we addScope:

 // serivces/auth.service
LoginGoogle(): Observable<IAuthInfo> {
  const provider = new GoogleAuthProvider();
  provider.addScope('email');
  // ...
}

The returned token does not have the email. Nice going Firebase! The extra piece of information is found in two places,

userCredential.user.providerData[]. An array of well-formed data (UserInfo[])
AdditionalUserInfo.profile. The format depends on the provider, needs to be requested via getAdditionalUserInfo but also has a very important piece of information: isNewUser. But we can do without it now.

For the particular case of Google sign in, we'll rely on the first method. But you might want to investigate further for X (Twitter) provider, and no, not Facebook, we're boycotting Facebook.

The change affects three places: LoginGoogle, LoginUser, and the route /auth/login:

// services/auth.service
// catch email in google, and send it to API
LoginGoogle(): Observable<IAuthInfo> {
 //...

  return defer(res).pipe(
      switchMap(auth => auth.user.getIdToken()),
            // login with provider email
      switchMap(token => this.LoginUser(token, this.auth.currentUser.providerData[0].email))
  );
}
// catch email and send to API
LoginUser(token: string, email?: string): Observable<IAuthInfo> {
    return this.http.post('/auth/login', { token, email });
}

On the server:

// in server/routes.js
router.post('/auth/login', function (req, res) {

  const payload = req.body;
  const token = payload.token;

  sdk.auth().verifyIdToken(token).then(function (decodedToken) {
    //...
    if (!profile) {
      // ...
      // read email from payload instead of decodedToken
      const _newuser = {
        email: payload.email
        // ...
      } 
      // ...
      res.json(_newuser);
    }
    //...
  })
});

Which means, we need to send the email with Sign in with Password. Let's also do the promised enhancement of combining sign in and sign up with password.

Combine sign in and sign up

For best user experience, we should allow user to sign in first, and if the user is new, request additional information for sign up. This matches the sequence of events handled with Google login, or any third party login.

In our component we need just one login call, that switches to sign up if the user is new.

// components/public/login.component
// change to login to allow sign up
login() {
  this.authService
    .Login('email@address.com', 'valid_firebase_password')
    .pipe(catchError...)
      .subscribe({
      next: (user) => {
        // read newUser from our API
        if (!user.newUser) {
          this.router.navigateByUrl('/private/dashboard');
        } else {
          // show the sign up field
          this.showMe = true;
        }
      },
   });
}

This looks exactly like the loginGoogle method. We are on the right track.

In our AuthService, the Login needs to change a bit, it will catch the invalid credentials error, to switch to SignUp.

// services/auth.service
// Login first
Login(email: string, password: string): Observable<IAuthInfo> {
  const res = () => signInWithEmailAndPassword(this.auth, email, password);
  return defer(res).pipe(
    switchMap(auth => auth.user.getIdToken()),
    // send email
    switchMap(token => this.LoginUser(token, email)),
    catchError(err => {
      // catch invalid credentials to sign up
      if (err.code === 'auth/invalid-credential') {
        return this.SingUp(email, password);
      }
      // throw everything else
      return throwError(() => err);
    })
  );
}
// remove custom attributes
SingUp(email: string, password: string): Observable<IAuthInfo> {
  const res = () =>
    createUserWithEmailAndPassword(this.auth, email, password);
  return defer(res).pipe(
    switchMap(auth => auth.user.getIdToken()),
    // stop here and return, send email as well
    switchMap(token => this.LoginUser(token, email)),
  );
}

Now the update and UpdateUser take care of patching the bloodType, just as in the Google sign in sequence. Great. Now what?

Authentication header

In order for the PATCH /user call to work, we need to pass a fresh token into the header. The following is the authentication middleware, nothing fancy, we just get the user from data source first, match to the uid returned by Firebase token.

// server/auth.middleware.js
// update to find profile by uid first
sdk.auth().verifyIdToken(authheader).then(function (decodedToken) {
  // example:
  let profile = profiles.find((profile) => profile.id === decodedToken.uid);
  // if found, set, else nullify
  if (profile){
    res.locals.user = profile;
  } else {
    res.locals.user = null;
  }
  // next
  next();
})
// ...

Our http interceptor is the same we created in the last episode. It too will have a 401 error catch, that will request a fresh token from Firebase. Let's dig in the AuthState and user model to see how we can save the token.

Maintaining state

The end result we want for the user state is to be able to display the information based on a state item (like the one we developed in our Angular Authentication series).

// components/some component
// template
`<div *ngIf="status$ | async as s">
  {{ s.email }} {{ s.bloodType }}
</div>`

status$: Observable<IAuthInfo>;
constructor(private authState: AuthState) {}
ngOnInit(): void {
  // watch auth state item
  this.status$ = this.authState.stateItem$;
}

Here are the ingredients:

An IAuthInfo to model our local user model
Update state after calling LoginUser and UpdateUser in AuthService
An AuthState service to keep track of user state
An AuthGuard to protect private route
Initiate the token property directly from Firebase

Auth user model

The IAuthInfo has the basic attributes, and a public method to map our user

// services/auth.model
export interface IAuthInfo {
  id: string;
  bloodType?: string;
  admin?: boolean;
  // some properties from firebase
  picture?: string;
  email?: string;
  // a place for the token
  token?: string;
  // a boolean for newUser
  newUser?: boolean;
}

export const MapAuth = (auth: any): IAuthInfo => {
  // map incoming from db with our user
  // this isn't required, but preferable
  // token is not mapped here
  return {
    id: auth.id,
    email: auth.email,
    admin: auth.admin,
    bloodType: auth.bloodType,
    picture: auth.picture,
    newUser: auth.newUser
  }
}

The token is not mapped directly from API, it will be added from Firebase.

Update service

After every visit to the API, we need to update the state, preferably by mapping to our local model, passing the fresh token coming back.

// services/auth.service
// update state after API calls
LoginUser(token: string, email?: any): Observable<IAuthInfo> {
  return this.http.post('/auth/login', { token, email }).pipe(
    map((auth: any) => {
      // map and save user in localstorage here, including token
      const _user = MapAuth(auth);
      this.authState.UpdateState({ ..._user, token });
      return _user;
    }),
  );
}
UpdateUser(custom: any): Observable<IAuthInfo> {
  return this.http.patch('/user', custom).pipe(
    map(auth => {
      // now update localstorage again
      const _user = MapAuth(auth);
      this.authState.UpdateState({..._user});
      return _user;
      })
  );
}

AuthState service

The main elements of our AuthState besides the constructor is a state item BehaviorSubject and a proper UpdateState method that updates the Subject and saves into local storage. It should inject the AngularFire Auth service as well. We should add the GetToken and RefreshToken to use in our http interceptor. Here it is 🔻

@Injectable({ providedIn: 'root' })
export class AuthState {
  // create an internal subject and an observable to keep track
  private stateItem: BehaviorSubject<IAuthInfo | null> = new BehaviorSubject(null);
  stateItem$: Observable<IAuthInfo | null> = this.stateItem.asObservable();
  constructor(
    // inject from '@angular/fire/auth'
    private auth: Auth
  )
  {
    // TODO: initiate state
  }

  UpdateState(item: Partial<IAuthInfo>): Observable<IAuthInfo> {
    // update existing state
    const newItem = { ...this.stateItem.getValue(), ...item };
    this.stateItem.next(newItem);
    // save into a key in localStorage
    localStorage.setItem('user', JSON.stringify(newItem));
    // return observable
    return this.stateItem$;
  }

  GetToken() {
    // return token as is
    const _auth = this.stateItem.getValue();
    return _auth?.token || null;
  }
  RefreshToken() {
    // refresh by calling getIdToken with `true`
    return defer(() => 
      this.auth.currentUser.getIdToken(true)).pipe(
      switchMap(token => {
        // update state then return an observable to pipe to
        return this.UpdateState({ token });
      })
    );
  }
}

Read more about a localStorage Angular wrapper, and RxJS based state management to have a fuller solution.

Auth route guard

The guard now reads directly from our state item.

// services/auth.guard

export const AuthCanActivate: CanActivateFn = (...): Observable<boolean> => {
  // inject our auth state
  const auth = inject(AuthState);
  const router = inject(Router);

  const role = route.data.role;

  // watch user
  return auth.stateItem$.pipe(
    map(_user => {
     // if user exists let them in, else redirect to login
      if (!_user) {
        router.navigateByUrl('/public/login');
        return false;
      }
       // user exists, match property to route data
      if (!_user.hasOwnProperty(role)) {
        router.navigateByUrl('/public/login');
        return false;
      }
      return true;
    })
  );
};

Initiate the token

When the application is launched, we can initiate the state from the local storage, through the same APP_INITIALIZER factory we already have. The constructor looks like this

// services/auth.state

constructor(...) {
  // initialize state directly from localStorage
    const _localuser: IAuthInfo = JSON.parse(localStorage.getItem('user'));
  if (_localuser) {
    this.UpdateState(_localuser);
  }
}

The most extreme case is when user lands on a protected route, and that user already has a saved state in local storage. The synchronous way of setting the initial state means the Auth Guard will have something to use. But the token used, is not only stale, but expired. What does that mean?

The curious case of an expired token

Should we expel user? Given the fact that Firebase token is designed around the idea of refreshing itself in an hour, we should not worry about it. Also remember, the route guard is cosmetic, the real security is on API. The next API call will throw a 401, which will initiate a refresh sequence.

We can also make sure that 401 doesn't happen as often, if we update the token on initialization at least once:

// services/auth.state

constructor(...)
{
  // .. update localStorage first
  // take just 1, this will only get a new one if it's expired
  idToken(this.auth).pipe(
    take(1),
  ).subscribe({
    next: (token) => {
      if (token) {
        this.UpdateState({ token });
      }
    }
  });
}

If changes occur off the system, like user changes their password, we simply have to wait till it expires. Or again, we can guard important actions with our own "forced" token. For example, to request a list of codes only after user is logged in, we can do this

// example of a tighter security call
GetSafeCodes(): Observable<something> {
  // first get token with force flag
  return defer(() => this.auth.currentUser.getIdToken(true)).pipe(
    switchMap(token => {
      // then call API if token exists\
      return this.GetCodes();
    }),
    catchError(...)
  );
}

Logout

Last bit to add is the logout, it is exactly like the one we had last episode, with the addition of cleaning localStorage in AuthState

// services/auth.state
Logout() {
  this.stateItem.next(null);
  localStorage.removeItem('user');
}

Conclusion

So this is it. Exposed and laid down. Here are some extra points to mention

Firebase Auth is a front layer that hides a lot of operations that take care of authentication, especially with third party
It is mostly asynchronous calls, returns Promises. This is a bit annoying, as you lose information down the pipe of multiple promises.
Use the modular SDK, for tree-shaking
The documentation will make you lose few pounds, or a few years of your life expectancy, if you are working with web, you have go through only these:
- Authentication for Web (And reference of auth JS functions)
- Admin SDK (with NodeJS) (And reference of Nodejs functions)
The decoded token of Firebase in Admin SDK has a different model than the one returned after user sign-in on client-side. For example, picture, is for photoUrl. There is no displayName in Admin SDK. There is a name property, but it is not documented!

In summary:

We created a NodeJs Express server to handle Firebase verification
We created a service that handles sign in, and sign up, with Password and Google, that have the same sequence
We saved information in our local storage
We hunted down the Firebase token, refreshed it when needed, and relaxed when it was okay, relied on 401 when it made sense
We looked into two different implementations, one is more recommended than the other, and it is my personal go for

Happy 2024. Are we there yet?

Thanks for reading this far, if you have comments and questions, let me know. 🔻

RESOURCES

Authentication in Angular, why it is so hard to wrap your head around it - Sekrab Garage

The basic ingredients. Authentication ingredientsA full cycle of authentication and authorization in an SPA may go through the following factors:<ul><li>User login: getting an access token, and possibly a refresh token.</li.... Posted in Angular

garage.sekrab.com

LocalStorage wrapper service in Angular - Sekrab Garage

Storage and Caching. Browser Storage is accessible in browser platform only, and it is just one way to cache in browser. Thus we should avoid accessing it directly in code, wrapping it with internal service allows us to.... Posted in Angular, Design

garage.sekrab.com

RxJS based state management in Angular - Part I - Sekrab Garage

Angular state management simple solution. Google it, Angular State Management, odds are, you will end up on an ngRx solution. Referring to this greate article Choosing the State Management Approach in Angular App , I am here to explore and i.... Posted in Angular, Design

garage.sekrab.com

II - Firebase User Management in Angular

Ayyash — Tue, 09 Jan 2024 10:00:00 +0000

To recap, we need to create a sign up process using password and Google provider. We need to keep all user management on Firebase. We need to add role admin, and bloodType attributes for every user.

One thing to keep in mind as we maneuver our way through Firebase Auth, you can get the token only on the client side, and you can set claims only on the server side.

Let's begin with the server routes, and see how we can set custom claims.

I had to ditch StackBlitz for this project, find the code final code on GitHub.

Setting custom claims

The page that user signs in, should have the extra field in it for bloodType. Let's create an API route for it: POST /api/user

// server/routes.js route to set custom claims
// the sdk created earlier is passed or can be imported directly
// const { getAuth } = require('firebase-admin/auth');
// const sdk = getAuth();

module.exports = function (sdk) {
  const router = express.Router();

  // update local user with custom claims
  router.post('/user', function(req, res) {
    // get user from middleware
    const user = res.locals.user;
    // read body params, could be an object
    const bloodType = req.body.bloodType;
    // set admin to true, set a new property bloodType
    sdk.setCustomUserClaims(user.uid, {admin: true, bloodType}).then(() => {
      // return user although we dont have to
      res.json({...user, bloodType, admin: true});
    }).catch(function(error) {
      res.status(401).json({
        message: 'Invalid token'
      });
    });
  });
  return router;
}
// pass this in main server like this
webapi.use('/api', require('./routes')(sdk));

In AuthService we pipe a swichMap to call this API. Let's not be too specific about typing today, thank God for any

// services/auth.service

// a new function to sign up, passing bloodType
Signup(email: string, password: string, custom: any): Observable<any> {
  const res = () => createUserWithEmailAndPassword(this.auth, email, password);

  return defer(res).pipe(
    // send back to API server to create user with custom claims
    switchMap(_ => this.UpdateUser(custom))
  );
}

UpdateUser(custom: any): Observable<any> {
  return this.http.post('/api/user', custom);
}

We could have sent the token in the body, but because updating users might be needed in a different context, we'll rely on the middleware instead. We need to add the authorization header to be sent for the second call. We'll do that right after we figure out Google provider.

Sign in with Google

To Sign in with password, all we have to do is return the user to the client-side, and start using it. The Sign in with Google however is a bit trickier. We have no clue whether the user exists or not. One way to find out is check the custom attribute bloodType. Another way is to check user metadata, which contains lastLoginAt, and createdAt, if they are milliseconds apart, this is a new user. But the best way is to check for additional user info right after login: getAdditionalUserInfo()

If the property isNewUser is set to true, we need to request the bloodType before we move on. So our service will just return the user, and let the component decide what to do with it:

// services/auth.service

// the login with google can check for new user:
LoginGoogle(): Observable<boolean> {
  const provider = new GoogleAuthProvider();

  const res = () => signInWithPopup(this.auth, provider)
    .then((userCredential) => {
      // import getAdditionalUserInfo from '@angular/fire/auth'
      const info = getAdditionalUserInfo(userCredential);
      return info.isNewUser;
    });
    return defer(res);
}

In the component, how to react to show a sign-up form is beyond the scope of this article. Once we get the bloodType, we call an update method (on click of submit button). There is nothing extra we need to set, because the middleware will received the token, verify and unpack the user, then set custom claims and return.

// components/public/login.component

loginGoogle() {
  this.authService.LoginGoogle().pipe(
    catchError(...)
  ).subscribe({
    next: (isNewUser) => {
      if (!isNewUser) {
      // log user in and redirect
        this.router.navigateByUrl('/private/dashboard');
      } else {
        // somehow redirect or show a sign up form
        someVarShowInput = true;
      }
    }
  });
}

// when bood type is provided, finish sign up
updateSingup() {
  this.authService.UpdateUser({ bloodType: 'B+' }).subscribe({
    next: (user) => {
     // logged in and signed up, redirect
     this.router.navigateByUrl('/private/dashboard');
    }
  });
}

Putting them together

One gap we might want to think about is if user signs up with Google, but does not continue to provide the bloodType. The better way is to rely on our API to check if it exists or not.

Also, a better user experience for the sign in with Password is to sign user in first, and if an error comes back, ask for the bloodType and sign up, which mimics the Sign in with Google.

We will do both in the next episode.

Adding the authorization header

The token in Firebase is wrapped inside the idToken subscription, but under the hood, it does not change during the session. We need to find a way to get that token at initialization, and keep it alive during the session.

We begin with the end in sight. The http interceptor function should have a way to add the bearer token:

// services/http.fn

// the getHeaders should add token from auth state
const getHeaders = (): any => {
  const authState = inject(AuthState);
  //  authorization here
  let headers: any = {};
  // to be implemented:
  const _auth = authState.GetToken();
  if (_auth && _auth !== '') {
    headers['authorization'] = `Bearer ${_auth}`;
  }
  return headers;
};

export const AppInterceptorFn: HttpInterceptorFn = (
  req: HttpRequest<any>,
  next: HttpHandlerFn
) => {
  const adjustedReq = req.clone({
    // ... prefix url here
    setHeaders: getHeaders(),
  });

  return next(adjustedReq);
};

We need an AuthState service with at least GetToken that returns a string, we can inject the Firebase Auth in it, and start listening to the idToken. We can keep the value in a BehaviorSubject to get the value when we need it.

// new services/auth.state
@Injectable({ providedIn: 'root' })
export class AuthState {
  // let the state have a behavior subject to keep track of value
  private token: BehaviorSubject<string> = new BehaviorSubject(null);
  token$: Observable<string> = this.token.asObservable();

  constructor(private auth: Auth) {
    // subscrine to id token changes
    idToken(this.auth).subscribe({
      next: (token) => {
        this.UpdateState(token);
      }
    });
  }

  GetToken() {
    return this.token.getValue();
  }

  // update state
  UpdateState(token: string) {
    this.token.next(token);
  }
}

This might look like a good idea at first, but if we immediately call the API, this method is too slow. The token is still null. Instead, we need to populate the state immediately after sign in or sign up. We need to further build the pipe with idToken

// services/auth.service
export class AuthService {
    constructor(
      private http: HttpClient,
      private authState: AuthState,
      private auth: Auth
    ) {}

    // pipe after login, or sign up, to save the token in state
    Signup(...): Observable<any> {
    // ... createUserWithEmailAndPassword

    return defer(res).pipe(
      // with idToken
      switchMap(_ => idToken(this.auth)),
      tap((token) => {
          // save state first
          this.authState.UpdateState(token);
      }),
        // then call backend
      switchMap(_ => this.UpdateUser(custom)));
    }
}

This will ensure that the header has the correct token before calling the API. All other API's can be taken care of with calling the AuthState immediately at creating the application, and where better to do that than APP_INITIALIZER? We already had this set up before:

// main.ts

// in our root providers array
bootstrapApplication(AppComponent, {
  providers: [
    // ...
    {
      provide: APP_INITIALIZER,
      // dummy factory
      useFactory: () => () => {},
      multi: true,
      // injected depdencies, this will be constructed immidiately
      deps: [AuthState],
    },
  ],
});

Auth route guard

In AngularFire documentation you can find a reference to built-in Auth guard functionality. We can make use of them, for example if we want to block a route for other than admins.

// main.ts (or in routing)
import { canActivate, hasCustomClaim } from '@angular/fire/auth-guard';
const adminOnly = () => hasCustomClaim('admin');

// define a route
{
  path: 'private',
  loadChildren: () => import('./app/routes/dashboard.route').then((m) => m.DashboardRoutes),
  // use canActivate
  ...canActivate(adminOnly)
}

They have other examples of mixing and matching and using claims. In our project, I would rather create our own guard:

// services/augh.guard
export const AuthCanActivate: CanActivateFn = (route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<boolean> => {
    const auth = inject(Auth); // @angular/fire/auth
    const router = inject(Router);

    // get data from route, for example {date: {role: 'admin'}}
    const role = route.data.role;

    // watch user (import from @angular/fire/auth)
    return user(auth).pipe(
      // switch map to get claims
      switchMap(_user => _user ? _user.getIdTokenResult() : of(null)),
      map(_user => {
        // if user exists let them in, else redirect to login
        if (!_user) {
          router.navigateByUrl('/public/login');
          return false;
        }
        // user exists, match claims to route data
        if (!_user.claims.hasOwnProperty(role)) {
          router.navigateByUrl('/public/dashboard');
          return false;
        }
        return true;
      })
    );
};

In routes:

// main.ts

{
  path: 'private',
  loadChildren: () => import('./app/routes/dashboard.route').then((m) => m.DashboardRoutes),
  canActivate: [AuthCanActivate],
  data: { role: 'admin'}
},

So by setting claims.admin to true, we gain access to the dashboard route.

The curious case of the stale token

After calling our API to set custom claims, the token has changed on Firebase, but it did not reflect in our client side. This could cause problems if we depend on the custom claims, the token on the client at this stage is stale. Here are some scenarios of what could go wrong, and we need to fix them.

After signing up and updating claims, redirecting to a private route that depends on custom claims admin attribute. The token does not have it.
Updating user bloodType to O- then within less than an hour, refreshing the application. The token still says B+. This is a life threatening situation!
Although rare: leaving a page open for an hour without any interactions, then calling an http with the current token. The server verification will fail.

Refresh after API update

In the first case, on the next augh.guard call , we used user() observable, which is wrapped around onIdTokenChange of Firebase (See code of rxFire). Then we called getIdTokenResult(). Here is the thing:

onIdTokenChange does not refresh the token
getIdTokenResult returns a new token only if the current token has expired (or about to).

None of the AngularFire observables is capable of refreshing the token. To refresh it, we need to call .getIdToken(true). So after an update statement, and before we redirect to a private route that uses the guard, we need to hard refresh the token. Since we are already listening to idToken in the pipe of signing up, this might create a loop. So let's decide now:

Use closer-to-home getTokenId() instead of idToken
Force a refresh with getTokenId(true)

Here is the Firebase documentation of what should happen in normal JavaScript.

And here is our Signup and UpdateUser

// services/auth.service
Signup(...): Observable<any> {
   // ...

  return defer(res).pipe(
    // first token, directly from getIdToken, this is good enough
    // because it is used after a Firebase function "create user"
    switchMap(_ => this.auth.currentUser.getIdToken()),
    tap(token => {
      // save state first, to use token
      this.authState.UpdateState(token);
    }),
    // then call update
    switchMap(_ => this.UpdateUser(custom))
  );
}

UpdateUser(custom: { bloodType: string; }): Observable<any> {
  return this.http.post('/user', custom).pipe(
    // force a new token, and wait for it
    // it must be a switchMap
    switchMap(_ => this.auth.currentUser.getIdToken(true)),
    tap(token => {
        // update state for future http calls
        return this.authState.UpdateState(token)
    })
  );
}

The switchMap in the UpdateUser is the best way to ensure the new token is returned from the Promise, other operators are too asynchronous to catch in the redirect.

Any call to the UpdateUser should now force update the token afterwards. Life saved.

Update state after Login

After login (from Firebase), we have no problems because the token received has custom claims, we however need to keep our AuthState up to date, with the idToken in the constructor that should be enough. But always pay attention, if there is any immediate http call after login, it must be called in place, the idToken subscriber might be too slow.

Let's refactor our AuthService

// services/auth.service

// a single pipe for all
private _updateState = (force: boolean) => pipe(
  switchMap(_ => this.auth.currentUser.getIdToken(force)),
  tap((token) => {
    // save state as well
    this.authState.UpdateState(token);
  })
);

Signup(email: string, password: string, custom: any): Observable<any> {
  // ...
  return defer(res).pipe(this._updateState(false),
    switchMap((_) => this.UpdateUser(custom))
  );
}

UpdateUser(custom: any): Observable<any> {
  return this.http.post('/user', custom).pipe(this._updateState(true));
}

Refresh 401 token

Instead of trying to keep the token fresh by manipulating events, it's better to let the API http call return a 401 when the token expires, then handle it.

Having the auth.guard on multiple routes is good enough to keep the token fresh. But it's not good enough to update our state with the new token.

We've already had this feature implemented in our Angular Authentication series. Here it is as an http interceptor function, for standalone, instead of an interceptor class.

// http interceptor with refresh token sequence
let isBusy = false;
let recall: Subject<boolean> = new Subject();

    const handle401Error = (originalReq: HttpRequest<any>, next: HttpHandlerFn, authState: AuthState): Observable<any> => {
    if (!isBusy) {
      isBusy = true;
      // progress subject to false
      recall.next(false);
    // this RefreshToken needs to be implemented
      return authState.RefreshToken().pipe(
        switchMap((result: any) => {
          if (result) {
            recall.next(true);
                  return next(
            // pass around the authstate injected
              originalReq.clone({ setHeaders: getHeaders(authState) })
            );
          }
        }),
        catchError((error) => {
          // logout may be? doesn't matter
          return throwError(() => error);
        }),
        finalize(() => {
          isBusy = false;
        })
      );
    } else {
      return recall.pipe(
        filter((ready) => ready === true),
        switchMap((ready) => {
        return next(
            originalReq.clone({ setHeaders: getHeaders(authState) })
          );
        })
      );
    }
};

export const AppInterceptorFn: HttpInterceptorFn = (
  req: HttpRequest<any>,
  next: HttpHandlerFn
) => {

  const url = 'prefixurl' + req.url;
  // inject and pass around
  const authState = inject(AuthState);
  const adjustedReq = req.clone({
    url: url,
    setHeaders: getHeaders(authState),
  });

  return next(adjustedReq).pipe(
    catchError((error) => {
      // if this is really an http error
      if (
        error instanceof HttpErrorResponse &&
        // and of 401 status
        error.status === 401
        // filter out login calls
        req.url.indexOf('login') < 0
      ) {
        return handle401Error(adjustedReq, next, authState);
      }
      // rethrow error
      return throwError(() => error);
    })
  );
};

The AuthState RefreshToken returns an observable that calls the getIdToken(true) to be sure it is fresh (though it isn't needed, we already know it will be refreshed).

// services/auth.state

RefreshToken(): Observable<any> {
  // defer, or from() have the same effect
  return defer(() => this.auth.currentUser.getIdToken(true)).pipe(
    tap((token) => {
      // update state with token for next http call
      this.UpdateState(token);
    })
  );
}

Tried it. And it works as expected. I had to create a page with a button and leave it for an hour till the token expired!

Off-app updates and sensitive changes

Another scenario often referred to in Firebase documentation in a subtle way is when the token that becomes invalid for changes happening off our app. For example if we have an admin portal where we can change the bloodType of a certain user, while they are using the client app. The token will expire in at least an hour. According to Firebase, that is okay. And it is, most of the time.

Firebase also suggests using re-authentication for serious actions, and it actively errors out on certain sensitive actions if user is not recently logged in. This scenario is out of scope of this article, but I just wanted to drive your attention that this is indeed a case with no solution. You just have to have soul.

Getting user custom attributes

In order to read the custom claims for the logged in user, we can use getUserTokenResult() then read the user.claims. We can do that by subscribing to the user AngularFire subscriber, or we can map to our internal user model, and update it upon sign in, sign up, and user update. All roads lead to Jerusalem. In a simple listener, we need to pipe (again):

// home.component
// an example of usning claims

// OnInit:
this.status$ = user(this.auth).pipe(
  filter(user => !!user),
  // use the promise directly, this works
  switchMap(user => user.getIdTokenResult()),
  map(token => token.claims)
);

// in the template
`{{ (status$ | async)?.bloodType }}`

But it is much better to wrap everything in a proper user model, that we can carry around, and scale as we go. We can place that in the AuthState as well, instead of wrapping the token alone, it can include all user properties. Mapping to an internal model is a subject we will dig into in the final recommended solution.

I have no idea what the point is in burying the claims a level too low like that!

Logout

To logout, we use the Firebase signOut then we need to nullify the token in our own AuthState. First inside the AuthService:

// services/auth.service

Signout(): Observable<boolean> {
  // signOut from '@angular/fire/auth'
  const res = () => signOut(this.auth).then(() => {
    this.authState.Logout();
    return true;
  });
  // catch error and return false if needed
  return defer(res);
}

Then in our AuthState

// services/auth.state
Logout() {
  this.token.next(null);
}

Finally in our component, a click handler:

// any component click handler
Logout() {
  this.authService.Signout().subscribe({
    next: () => {
      this.router.navigateByUrl('/public/login');
    }
  })
}

Let us move on to the other recommended solution. Next Tuesday inshalla. 🔻

RESOURCES

Authentication in Angular, why it is so hard to wrap your head around it - Sekrab Garage

garage.sekrab.com

Forem: Ayyash

Putting Angular Fire Firestore library to use - II

Mapping data

Create document

The curious case of Firestore syntax

Update document

Delete document

Querying responsibly

Timestamp

Firestore Lite

Interception

Resources

Related posts

Putting Angular Fire Firestore library to use - I

Setup

The Firestore reference

Note about referencing the right SDK

Get data

Getting the document id

Get by document ID

Query

Cold observables

Mapping data

References:

Angular Firebase Authentication Update: v.19

Providers

APP_INITIALIZER token

Validation style final tweaks

Checkbox

Testing the edges

Testing another edge case: Nice looking checkbox

Hidden fields

Auto-filled fields

Bonus: standalone imports

Conclusion

Resources

Angular validation common functions

Date

Enrich the inline validator

A date range selector.

Password

Upload

At least one

Styling

References

Angular form field types

Textarea

Select box

Checkbox

Multiple checkboxes

Radio button

Hidden field

Validation common functions

Resources

Angular form validation directive

Directive

The error message property

Edge case: min and max

Reverse range

Length

Pattern

Note about text

Email validation

Custom validation

Cross form validation

Form validation

Add a new property for cross field validation

Issue: Multiple error messages

Using the directive in other ways

The best experience

Form types

Resources

Related posts

Taming Angular Forms

Opening the input box

Preparing for floating labels

Validation

Resources

Upgrading to Angular version 19

Updating to Angular 19