DEV Community: Cristian-Florin Calina

A11y: Vanilla javascript aria-live announcer

Cristian-Florin Calina — Sun, 18 Feb 2024 08:41:49 +0000

Since I've worked with Angular & Angular Material for a few years, I got used to a lot of the nice features that it provides out of the box.

One of those features, that I didn't use a lot, but it was a useful one nonetheless was the LiveAnnouncer from Angular Material.

This provided a nice API to announce messages to the screen reader.

I found some use cases for this while working on non Angular projects, and I wanted to check if there was a vanilla javascript solution that would standardize the consumption of the aria-live attribute.

I found some react live announcers, but no package that would expose a vanilla javascript live announcer, so I decided to create my own (didn't do a thorough search since I was a bit interested to build one).

Concept of AriaLiveAnnouncer

I started with a simple idea:

Expose a class called AriaLiveAnnouncer that when initialized, it would insert a singleton DOM element with a configurable aria-live politeness setting.

type Politeness = 'off' | 'polite' | 'assertive' 

const UNIQUE_ID = '__aria-announcer-element__';
const DEFAULT_POLITENESS = 'polite';

interface AriaLiveAnnouncerProps {
    politeness?: Politeness;
}

export class AriaLiveAnnouncer {
    static #instantiated = false;
    static __DEBUG__ = false;

    #rootElement;

    constructor({ politeness }: AriaLiveAnnouncerProps = { politeness: DEFAULT_POLITENESS}) {
        this.init({ politeness });
    }

    init({ politeness }: AriaLiveAnnouncerProps = { politeness: DEFAULT_POLITENESS }) {
        if (AriaLiveAnnouncer.#instantiated) {
            AriaLiveAnnouncer.__DEBUG__ && console.warn('AriaLiveAnnouncer is already instantiated');
            return;
        }

        AriaLiveAnnouncer.#instantiated = true;

        this.#politeness = politeness;

        this.#rootElement = document.createElement('div');
        this.#rootElement.id = UNIQUE_ID;
        this.#rootElement.style.width = '0';
        this.#rootElement.style.height = '0';
        this.#rootElement.style.opacity = '0';
        this.#rootElement.style.position= 'absolute';
        this.#rootElement.setAttribute('aria-live', politeness);

        document.body.appendChild(this.#rootElement);
    }
}

This class would also have an announce method, that would be called with a message and a politeness override. This will announce the message to the screen reader (by changing the content of the element), and then reset the content of the DOM node & the politeness to the initialized one.

    // method that will post a message to the screen reader
    announce(message: string, politeness: Politeness = this.#politeness) {
        if (!this.#rootElement) {
            AriaLiveAnnouncer.__DEBUG__ && console.warn('AriaLiveAnnouncer not initialized, please use init() method');
            return;
        }

        // temporary change the politeness setting
        this.#rootElement.setAttribute('aria-live', politeness);
        this.#rootElement.innerText = message;

        // cleanup the message and reset the politeness setting
        setTimeout(() => {
            this.#rootElement.innerText = null;
            this.#rootElement.setAttribute('aria-live', this.#politeness)
        }, 100)
    }

Add a destroy method to cleanup the node from the DOM, reset the singleton and allow for reinitialization via an init method exposed as well.

    // Cleanup method that will remove the element and reset the singleton
    destroy() {
        document.body.removeChild(this.#rootElement);
        this.#rootElement = undefined;
        AriaLiveAnnouncer.#instantiated = false;
    }

Simple enough, so I implemented it, but as soon as I started testing it I noticed some improvement opportunities:

First of all, I had to decide on the delay between announcing and cleaning up the content. I initially went with a default, but decided to make it customizable from the consumer.

interface AriaLiveAnnouncerProps {
    politeness?: Politeness;
    processingTime?: number;
}
//...same as before
const DEFAULT_PROCESSING_TIME = 500;
//...
export class AriaLiveAnnouncer {
    //...
    #processingTime = DEFAULT_PROCESSING_TIME;
    //...

    constructor({ politeness, processingTime }: AriaLiveAnnouncerProps = { politeness: DEFAULT_POLITENESS, processingTime: DEFAULT_PROCESSING_TIME }) {
        this.init({ politeness, processingTime });
    }

    // Init method to allow consecutive `destroy` and `init`.
    init({ politeness, processingTime }: AriaLiveAnnouncerProps = { politeness: DEFAULT_POLITENESS, processingTime: DEFAULT_PROCESSING_TIME}) {
        //...same as before
        this.#processingTime = processingTime;
        //...
    }

    announce(message: string, politeness: Politeness = this.#politeness) {
        //...same as before but use `this.#politeness` for the timeout
    }
}

After that, I thought about what would happen if the announce method was called multiple times while the element was not yet cleaned up or announced. So for this, I added an announcement queue that would process each message based on the configured time, and simply add to this queue while it's processing existing items.

export class AriaLiveAnnouncer {
    //...
    #announcementQueue = [];
    #isAnnouncing = false;
    //...

    // method that will post a message to the screen reader
    announce(message: string, politeness: Politeness = this.#politeness) {
        if (!this.#rootElement) {
            AriaLiveAnnouncer.__DEBUG__ && console.warn('AriaLiveAnnouncer not initialized, please use init() method');
            return;
        }

        this.#announcementQueue.push({ message, politeness });

        if (!this.#isAnnouncing) {
            this.#processQueue();
        }
    }

    //...

    // Recursive method to process the announced messages one at a time based on the processing time provided by the consumer or using the default
    #processQueue() {
        if (this.#announcementQueue.length > 0) {
            this.#isAnnouncing = true;

            const { message, politeness } = this.#announcementQueue.shift();

            this.#rootElement.setAttribute('aria-live', politeness);
            this.#rootElement.innerText = message;

            setTimeout(() => {
                if (!this.#rootElement) { 
                    return;
                }

                this.#rootElement.innerText = '';
                this.#rootElement.setAttribute('aria-live', this.#politeness);

                this.#processQueue();
            }, this.#processingTime);
        } else {
            this.#isAnnouncing = false;
        }
    }
}

The problem now was if the destroy method was called while there was still items left in the queue. So for this, I gracefully joined the existing messages left in the queue (each on a new line) and announced them all at once, then cleaned up.

    destroy() {
        const remaining = this.#announcementQueue.length;

        if (remaining > 0) {
            AriaLiveAnnouncer.__DEBUG__ && console.warn(`Destroying AriaLiveAnnouncer with ${remaining} items left to announce. Announcing them all at once`);

            this.#rootElement.setAttribute('aria-live', this.#politeness);
            this.#rootElement.innerText = this.#announcementQueue.map(v => v.message).join('\n');
            this.#clearQueue();

            setTimeout(() => this.#cleanup(), this.#processingTime);
        } else {
            this.#cleanup();
        }
    }

    #clearQueue() {
        this.#announcementQueue = [];
        this.#isAnnouncing = false;
    }

    // Private cleanup method that removes the element and resets the announcement queue & singleton
    #cleanup() {
        document.body.removeChild(this.#rootElement);
        this.#rootElement = undefined;
        this.#clearQueue();

        AriaLiveAnnouncer.#instantiated = false;
    }

Consumption of AriaLiveAnnouncer

Consumption is very straightforward:

Install the package

npm install aria-announcer-js

Consume it

import { AriaLiveAnnouncer } from 'aria-announcer-js';

// defaults are 'polite' and '500' 
const announcer = new AriaLiveAnnouncer({ politeness: 'polite', processingTime: 500 });

// Announce a message
announcer.announce("Hello, world!");

And that's it ! It was a quick nice little project (maybe overengineered a bit) and I decided to share it as well if anybody has the need for something like this and does not want to implement it from scratch (you can find it on github and on npm).

Hope it's useful or at least a nice read !
Thank you!

How to cherry-pick from separate repos with separate paths (with history)

Cristian-Florin Calina — Sun, 05 Feb 2023 22:09:47 +0000

If you ever wanted to extract parts of code from one repository to another one, but you also wanted to keep the history of commits for those parts, there is a way.

You can use

git log --pretty=email --patch-with-stat --reverse --full-index --binary -- <file_path | folder_path> > ~/toggle.patch

Explained:
--pretty=email formats the output to show the hash, the date, the author, author date and subject + the commit message.

--patch-with-stat generates a diffstat for the file/folder

--reverse outputs the commits in reverse order (so that they can be applied in the correct order in the other repository).

--full-index this shows the full index of the commit when outputing the diffs (instead of showing just the first characters).

--binary outputs the diff in binary so that git-apply can use it.

This will generate a patch file with the differences that were done on the file or folder that you pass to it (and will keep commits history as well).

After that, you must mass edit the generated toggle.patch file by changing the paths in diffs to match the new paths in the new repo.

After you changed the patch, you can apply it in your new repo by using

git am --committer-date-is-author-date < ~/toggle.patch.

Explained:
--commiter-date-is-author-date allows the user to lie about the committer date by using the same value as the author date.

This way, you keep all of the history for this extracted file/folder (and you keep the dates as well when looking over the file history).

Hope this helps.

Media Queries in JS/TS done right

Cristian-Florin Calina — Mon, 05 Dec 2022 18:01:45 +0000

Recently, I had a situation that involved listening to the screen width of an application.
There are a lot of methods of achieving this, but I wanted something simple, reusable & generic that did not impact performance too much.

I thought that listening to resize event on window and checking the innerWidth is way too slow especially since everything related to layout forces a reflow.

I discovered quickly while searching for solutions, the window.matchMedia() API and it seemed like that was the best solution (it is also supported in all of the major browsers).

The only thing left to do, was to implement a simple, reusable & generic solution that uses this underneath. Here's a helpful MDN link that got me started.

What I wanted was to be able to subscribe to different media queries from different components across the application, without creating new listeners.

The solution I came up with, was to create a static class (well, a class with static methods and variables), that would keep a list of queries & subscriptions for those queries (and a list of listener refs so it can be easily cleaned up).

export interface IQueryList {
    [key: string]: {
        query: MediaQueryList;
        subscribers: Array<(matchesQuery: boolean) => void>;
    };
}

interface IEventListener {
    [key: string]: (event: MediaQueryListEvent) => void;
}

export class MediaQueryListener {
    private static _subscribers: IQueryList = {};
    private static _eventListenersRefs: IEventListener = {};

    static subscribe() {
        //...
    }
    static unsubscribe() {
        //...
    }
}

This class would expose 2 public methods: subscribe and unsubscribe.

The subscribe method takes a callback function that receives a boolean parameter representing if the query matches or not, and the actual query in a string format (eg: '(max-width: 768px)').
It then checks if there is already a subscription made for this query from some other place:

if it is, it only adds the callback to the list of subscribers for that query.
if it's not, it adds the query to the list, with the only subscriber being the passed callback, then it starts to listen to changes for the newly created query.

Eitherway, it also calls the callback instantly with the current query match.

static subscribe = (cb: (matchesQuery: boolean) => void, query: string) => {
    if (!this._subscribers[query]) {
        this._subscribers[query] = {
            query: window.matchMedia(query),
            subscribers: [ cb ],
        };

        // keep the refs so we can remove the listeners in unsubscribe
        this._eventListenersRefs[query] = event => {
            this._subscribers[query]
                .subscribers
                .forEach(subscriber => subscriber(event.matches));
        };

        // create the listener only on first subscription for the query
        this._subscribers[query]
            .query
            .addEventListener('change', this._eventListenersRefs[query]);
    } else {
        this._subscribers[query].subscribers.push(cb);
    }

    // Call the callback with the current value of the media query
    cb(window.matchMedia(query).matches);
};

The unsubscribe method receives the same callback function & query in a string format, and removes the callback from the subscribers of that query. It also checks if there are no more subscribers left, and removes the media query listener so there are no hanging listeners left.

static unsubscribe = (cb: (matchesQuery: boolean) => void, query: string) => {
    if (!this._subscribers[query]) {
        return;
    }

    this._subscribers[query].subscribers = this._subscribers[query].subscribers.filter(subscriber => subscriber !== cb);

    if (this._subscribers[query].subscribers.length === 0) {
        this._subscribers[query].query.removeEventListener('change', this._eventListenersRefs[query]);

        delete this._subscribers[query];
        delete this._eventListenersRefs[query];
    }
};

As I said, it's a basic wrapper on top of matchMedia api. There are probably multiple packages out there that achieve the same thing in a way or another, I did not research specifically for those packages in advance before creating my solution since I liked the idea of writing one.

Thanks for reading the article !

Inversion of Control: Service Locator in Typescript

Cristian-Florin Calina — Mon, 24 Oct 2022 06:06:03 +0000

I've been working with Angular for a while now (over 2 years), and since I moved to another workplace, I've switched (mostly) to Stencil.

Stencil is a very nice compiler for Typescript that generates web components. If I were to place it, it would be a mixture between Angular and React. It uses decorators like Angular does (for the compiler to collect metadata and generate the output code based on that), and jsx/tsx with lifecycles just like React. It is a very powerfool tool to generate design systems.

In this design system that I've been working on, there was the problem of how to store the global state. I wanted to have a similar version to Inversion of Control (since I really liked it in Angular). The big advantage of using a IoC system is that you can easily mock the services in tests, instead of needing to overwrite the actual imports in jest (overwriting is fine, but on complicated setups where you want different configurations between iterations, it would get messy because if there is any reference to the module before it is mocked, the mock will not work).

So I came up with a simple solution for a global injectable service that did not care about the actual implementation.

First step would be to think about what the service that you want to write will do. Based on that, you can declare an interface with all the public methods of the service. Let's consider a simple service that sets and gets user information.

Then we would need to declare a UserServiceInstanceResolver static class that will receive an instance of a class implementation of this interface, and store it in order to be able to access it.

Last but not least, we can implement the actual service

And finally, whenever you want to actually instantiate the singleton service, you can just do it as such:

And the actual benefit, whenever you want to test any other component that uses this instance, you can easily instantiate a mock of the app on UserServiceInstanceResolver.Instantiate method.

This was all that I actually needed (just a root level global instance). But this code can be extended to support as well a per component instance (or hierarchy instance) and get a closer experience to Angular's DI.

Thank you for reading my article. If you enjoyed it, please hit that heart button so others can see it.

LE:
After seeing some of the comments, I agree that this is not the best pattern to use, and maybe you should use existing solutions from the implementors of typescript such as tsyringe or even decoration-ioc (which is the extraction of implementation of DI in VSCode). One of the reasons I like writing articles when I explore new ideas is that I can get instant feedback and learn new things so that I can improve those solutions, so thank you for that !

Improving Angular initial load time

Cristian-Florin Calina — Sat, 25 Jun 2022 00:27:14 +0000

If you happen to be working on a large Angular application, you might encounter issues with the initial load time of your app.

If you use performance metrics such as the new Performance Insights Chrome dev tool (which is a very nice tool to explore your network requests, layout shifts, rendering, TTI (time to interactive), FCP (First Contentful Paint), etc. , and get insights from google on how to fix some of your main issues), or Google Lighthouse extension, you might see that your TTI might be slow. This is bad for the users since if you don't have an application that loads fast, a lot of consumers lose interest.

There are a lot of solutions for those issues, and most of them are not even related to the front end application. This article is only targeting Angular specific performance improvements tips for front end engineers/developers.

1. Lazy loading is your friend

If you are working on a large codebase, chances are that you have a lot of modules, and your main bundle might be very big. This usually slows down the execution of the scripts, so you have a slower interactive page.

The easiest way in angular to fix this is to lazy load most(or all) of your routes. This way, when a user loads a page, the chunk that is served to him only contains what is required for the route, and not modules that are not needed right now (thanks to Angular Ivy, tree shaking done by angular is great, it eliminates whatever is not used from angular, your job is to eliminate what is not used from your app for the initial load as well).

You can write a custom preload strategy to start fetching the rest of the modules in the background (or common used modules, if you use telemetry and know which ones are the most accessed ones), so they are already loaded when the user will navigate away from the current page.

2. Split vendor chunk

This is not really recommended in production by the angular team in the official docs.

But hear me out: If you have a CDN that serves even your chunks (you have a great deployment pipeline that publishes your build to CDN), between two separate deploys usually the third party libraries don't change so it can be served from cache still, which is a bit faster. And your main bundle will contain only your application logic, so it will be smaller.

It might not be for you, here is a great discussion on the subject that I found on stackoverflow.

3. APP_INITIALIZER should not be very heavy

If you use APP_INITIALIZER, you know that angular will wait for everything in this provider to be finished during the application bootstrap phase.

This might tempt you to put a lot of async requests that might depend on each other but are required for the full global state of the app. You should avoid this, since it will delay angular and the time to interactive will be slower for the users.

If your application is already using this injection token and it's very hard to refactor, you might want to use a caching mechanism. You might want to make the request if there is nothing in the cache, but if it is, serve from there and start a new request in the background to update the cache without blocking angular. Maybe this is easier than refactoring, depending on your use case. Only problem would be that if you initialize an app state with this data, you might want to patch it as well after the background request has been made.

4. Startup API requests parallelizing / caching

A good performance monitoring solution is to check the network tab when initially loading your page. Check the API requests. Maybe you have a request that is triggered after another one, and so on. Check if anything can be parallelized in order to obtain a smaller waterfall time (if the requests are blocking the content).

You might want to delegate assets serving to service workers. Also, maybe you have large requests that do not change often. You might want to configure a service worker to cache those as well (this article might help you get started).

5. Analyze your webpack bundle

There is a nice npm package, webpack-bundle-analyzer. If you build your angular application in production mode, with the stats-json option, you can use it with this package by passing the location of the stats.json file to it.

After you run this command, a browser tab will open up showing you your webpack bundle. You can analyze how much of it is in the main.js, how much is in vendor.js (if you split the vendor chunk), and how much of it is lazy loaded. This way you can check your progress in reducing the bundle size. You can also determine what pieces of code are large in the chunk, and decide to import those on demand maybe (so they will not be in the main chunks).

6. Use telemetry to get actual prod performance

On your local machine, lighthouse or performance insights might give you fantastic results. The actual results for consumers in production might be really different from what you see (and there are a lot of reasons for this, such as internet speed, machines performance differences, and so on).

That's why, you might want to add performance telemetry in your application. A good solution for telemetry is Azure Application Insights. Here's a great article for integrating it with your angular application.

After you have your configuration ready, you can now track events into app insights. Only thing left to do is to actually track your performance. You can use the performance api for this. Maybe PerformancePaintTiming is enough for your needs. I'll work on an article to provide a concrete example on how to track performance in a simple angular app and query app insights to see actual metrics (and link it to this article). In the meantime, this is a good article as well that helps you track page load times for all of your routes and shows you how to query them.

As a conclusion, there are a lot of reasons why performance might be slow for some of your users. A lot of the issues are not really the responsibility of front end developers (slow API requests for example, or bad server configurations, bad scalability, etc.), but on large enterprise applications, there might be a lot of improvements that can be done on the front end application to ensure good load times.

If you have any suggestions or corrections for any of the steps, please let me know. I think it's important to learn from each other.