DEV Community: Alex Inkin

Maskito: a Holy Grail of input masking

Alex Inkin — Sun, 02 Jul 2023 12:10:29 +0000

If you have ever worked on complex user forms, you definitely needed a masking solution. You want your numbers to be properly formatted so it is easy for users to make sure they have entered the correct amount at a glance. Or compare credit card number with an actual card, enter their phone or birthday or an appointment time. Masking has a lot of use cases on the web but to find a good solution is not an easy task. A lot of the time masking libraries can cause frustration for both developers and users. Common issues are jumping caret, troubles with added symbols like dashes or brackets, browser autofill or errors in server side rendering and convoluted API.

We were no strangers to these troubles and at some point we decided to dedicate serious resources to our own solution. Today I would like to present it to you and explain why it is worth your attention.

What is Maskito and why should you care?

Maskito is a set of libraries for input masking with focus on both UX and DX. You can check out our extensive documentation portal. There you can find plenty of examples, as well as a detailed walkthrough of the API. The “Getting started” section will explain the basics and will quickly get you familiar with concepts and use cases. You can also read a more technical article by Maskito lead developer Nikita Barsukov.

Of course, Maskito is not the only solution you can find. But I believe there are certain things setting it apart from most alternatives available right now. Hence the ambitious title of this article. Let’s briefly explore why you should consider Maskito if you are looking for a masking solution for your project.

Backed by enterprise

Unlike many open source libraries that are maintained by individuals, Maskito is a product developed and used by one of the world’s leading fintech companies. We are seasoned open source authors getting paid for what we do so you can rely on timely support and continuous development.

Our team already has a stock of welcomed projects, especially in the Angular ecosystem, such as Taiga UI, ng-polymorpheus and Web APIs for Angular to name a few. We take them very seriously because they are not pet projects or hobbies (although we love them as if they were). Therefore you can expect our documentation to be easy to navigate, examples to be plentiful and communication to go effortlessly.

Framework agnostic

Whether you use React, Vue or Angular for your product or you rely on some other framework or even vanilla JavaScript — Maskito got you covered. Our main package is dependency free and can be used in any frontend application. And so are mask presets that we will cover below.

At the time of writing we have dedicated packages to use Maskito in React, Vue and Angular with comfort. Since the public API is rather succinct, it would be easy to expand support to other popular frameworks. Actual masking configuration is the same and can be shared across different projects and architectures with ease.

Environment agnostic

Maskito works in all modern browsers regardless of the environment you run it in. You can be using Web Components with Shadow DOM or employ SSR to improve your time to interactive and SEO — your inputs will not give you trouble by trying to access ‘window’ under nodejs or messing with encapsulated focus. It will also work properly on touch devices and virtual keyboards on both inputs and textarea elements. Clipboard interaction, undo/redo, text drag and drop or browser autofill are also covered by Maskito.

Our goal is to create a go-to masking solution for the web and the web is as diverse as it gets. If you face any issues with some specific configuration, please do not hesitate to raise an issue.

Quality code

Maskito is maintained by an experienced lead developer and a team of contributors with a history of delivering widely used versatile solutions and open source libraries. Multiple Google Developer Experts curate the project and make sure architectural decisions are well thought through and make sense in the long run.

All code is written in strict TypeScript and covered by tons of e2e tests and community contributions are thoroughly reviewed. We have tightly configured linters and automated pipelines we perfected for years on other projects to make sure technical flaws do not make it to the release. We use it in a multi million users business product. It is in our best interest that the caret does not jump all over your input fields.

Not just us

While we of course trust our solution and are happy with it, you might be wondering if it would suit your particular needs. We have a wide array of products with different browser and device usage, different specs and requirements. Our team consists of engineers that specialize in generalized solutions and flexible APIs. So we know there’s an endless pool of use cases and we are prepared.

But it is not just us — Ionic Framework, a multi platform UI solution with nearly 50k stars on GitHub has adopted Maskito as its official masking library recommendation. Their team did an investigation of existing alternatives and considered an option to develop their own mask. They decided Maskito would satisfy the needs of their extremely varied user base and added examples of masking their components to the documentation.

Ready to use

Maskito comes with a dedicated package of ready-to-use masks. We maintain a huge components library that has number formatting, credit cards, phones, dates etc. It is used in dozens of applications across our ecosystem, where additional masking is required for zip codes, IP addresses, serial numbers and so on. Once they are implemented and properly tested, all generally applicable cases are extracted and reused.

This is an ever growing collection of presets that you can take as-is and be sure they behave properly. You can contribute to it or raise a feature request for a particular solution at our GitHub repository. This makes Maskito as tiny or as comprehensive as you need it to be. Core package is only about 3KB gzip and every piece of presets is tree shakable so your bundle is in safe hands.

Summary

Maskito is free for both personal and commercial use and is released under Apache 2.0 license. I am really proud of what the team is doing and believe it to be the best solution for the task. I hope it can help you bring your ideas to life in a smooth way both for your users and developers. Check Maskito out and if you like it, support us with a star and help us spread the word. Happy masking everyone!

Taiga UI: A year in Open Source

Alex Inkin — Fri, 24 Dec 2021 13:28:19 +0000

Taiga UI is a huge Angular components library. We at Tinkoff were developing it closed-source for a couple of years before finally going public with a second major version. It’s been a year since our open source release and today I want to look back at this part of our journey and lay down some plans for 2022. Let’s go!

Open source

Over this time the community started to build up. One benefit for going open source on GitHub is contribution made simpler even for colleagues from different projects. The environment is familiar, no extra authentication or VPN required and the pipeline is clear.

We also spent quite some time to improve our processes utilizing many different tools to help us ship new versions safer and faster.

Taiga UI is a monorepo that includes several libraries and a demo application that we deploy using GitHub Pages. Now it is managed by NX tools that provide a lot of useful commands and increase speed of building and testing at both local development and CI/CD pipelines. If you plan on working with monorepos you should definitely try NX!

Whenever a Pull Request is created we need to be able to quickly checkout the changes. Reading code diff is great, but sometimes you just need to tinker with the new version, test it on mobile, different browsers and OS. Cloud services are perfect for this case, they allow you to deploy the code temporarily and access it with a link from any device. We chose Firebase to host it for us and a Github action posts a link to the deployment as a comment in the Pull Request. It works like a charm and speeds up code reviews a lot. Read this article to set it up on your repository!

Moreover, every PR runs a set of Cypress screenshot tests that iterates over the demo portal and compares current components with their reference from the main branch. Cypress has a commercial solution where you can easily access failed screenshots through a dashboard. But we created a little Github bot that stores failed screenshots in a temporary branch and posts them to the PR as a comment, updating it on every push. This makes identifying problems with the UI library fast and easy. We opensourced this bot so you can use it too, read this article going over it in detail!

There’s also a husky precommit hook with ESlint and Prettier fixing and formatting changed code on every commit with lint-staged which makes sure malformed code doesn't even make it to the Pull Request. Combined with standard-version and strict commit messages it makes releasing and changelog generation a breeze. For a contributor the workflow is as smooth as:

fork → npm ci → npm start → code → commit → push

What’s new?

When 2.0 went public it already was pretty big. But over the course of 2021 we added and improved a lot of things. With ideas and help from the community we significantly expanded customization and localization capabilities. This would be very helpful for our own international projects too. Taiga UI today has over 10 languages for built-in texts, RTL support for most of the components and various formats for money and dates. We also provide “ng add” schematic to get you started smoothly with Taiga UI. Let’s look at the most notable additions to our 150+ components base this year!

New components

Sheet — mobile sliding dialog

Tree — a flexible component to display tree-like data structures

PdfViewer — a custom dialog to preview PDFs in iframe

Carousel — a common UI pattern for slider of images

ArcChart — a new way to display numerical data

New add-on packages

Table — an interactive table component and related utilities

Editor — a rich text editor based on tiptap 2

Preview — a custom dialog to preview aribtrary content such as images and documents

We’ve also added a bunch of helpful utils, tokens, services and directives, such as Pan, Swipe, DropdownHover and more and a night theme for all components:

What’s coming?

It was a productive year. We’ve grown a lot in infratructure and content, we started to build community of users, most notably from cryptocurrency area as it seems from the screenshots that come with user questions 🙂 In the coming year we plan to exapand our localization and internationalization options so that developers from across the globe can enjoy Taiga UI and use it in whatever project they are working on. Here’s a brief overview of what we plan to focus on in 2022:

Improve and stabilize new Editor add-on package
Make all native inputs accessible from the outside of Taiga UI controls so it’s easy to assign attributes and listen to native events
Rework some of our internals to rely more on CSS and less on JavaScript which would reduce change detection cycles
Utilize DI more for customization
Drop dependency on global styles
Create ComponentHarnesses for Taiga UI components so they can be easily tested
Support different implementations of notifications, like we do now for dialogs
Reduce tech debt such as old components waiting for refactor and outdated mask library
Prepare for the next major release with Angular 13 and Ivy distribution

I hope you’re happy with Taiga UI and if you didn’t try it — please give it a shot! Feel free to open GitHub discussion or contact us over at Angular Discord. For Russian speaking users we have a Telegram chat. Our issues list is open for feature requests and bug reports. And it also always has some things for you to try and solve if you want to contribute! Merry Christmas and an awesome New Year to you all! 🎄

Demystifying Taiga UI root component: portals pattern in Angular

Alex Inkin — Tue, 26 Jan 2021 12:14:59 +0000

Just before new year, Roman, my colleague, announced our new Angular UI kit library Taiga UI. If you go through Getting started steps, you will see that you need to wrap your app with the tui-root component. Let's see what it does and explore what portals are and how and why we use them.

What is a portal?

Imagine you have a select component. It has a drop-down block with suggestions. If we keep it at the same position in DOM as the hosting component, we will run into all sorts of trouble. Items pop through and containers can chop off content:

Verticality issues are often solved with z-index, effectively starting World War Z in your app. It's not uncommon to see values like 100, 10000, 10001. But even if you manage to get it right — overflow: hidden would still get you there. So what can we do? Instead of having drop-down near its host we can show it in a dedicated container on top of everything. Then your application content can live in its own isolated context eliminating z-index problems. This container is exactly what a portal is. And it is what the Taiga UI root component sets up for you, among other things. Let's look at its template:

<tui-scroll-controls></tui-scroll-controls>
<tui-portal-host>
    <div class="content"><ng-content></ng-content></div>
    <tui-dialog-host></tui-dialog-host>
    <ng-content select="tuiOverDialogs"></ng-content>
    <tui-notifications-host></tui-notifications-host>
    <ng-content select="tuiOverNotifications"></ng-content>
</tui-portal-host>
<ng-content select="tuiOverPortals"></ng-content>
<tui-hints-host></tui-hints-host>
<ng-content select="tuiOverHints"></ng-content>

Generic and dedicated portals

Both tui-dialog-host and tui-portal-host are portals in their nature. But they work differently. Let's explore the second one first. Taiga UI uses it mostly to display drop-downs. But it's a generic container. It is controlled by a very simple service:

@Injectable({
  providedIn: 'root',
})
export class TuiPortalService {
  private host: TuiPortalHostComponent;

  add<C>(
    componentFactory: ComponentFactory<C>,
    injector: Injector
  ): ComponentRef<C> {
    return this.host.addComponentChild(componentFactory, injector);
  }

  remove<C>({hostView}: ComponentRef<C>) {
    hostView.destroy();
  }

  addTemplate<C>(
    templateRef: TemplateRef<C>,
    context?: C
  ): EmbeddedViewRef<C> {
    return this.host.addTemplateChild(templateRef, context);
  }

  removeTemplate<C>(viewRef: EmbeddedViewRef<C>) {
    viewRef.destroy();
  }
}

And the component itself is rather straightforward. All it does is show templates and dynamic components on top of everything. No other logic is included (except a little position: fixed helper for iOS). It means that positioning, closing and the rest is handled by portal items on their own. It's a good idea to have a generic portal for special cases. Like a fixed «Scroll to top» button displayed above content or anything else you, as a library user might need.

Drop-downs

If we were to architect a drop-down — we would need to come up with a positioning solution. We have several options here:

Position drop-down once and prevent scrolling while it's open. This is what material does by default.
Position once and close if scrolling occurred. That's how native drop-downs behave.
Follow host position when it changes

We went with the third option. It's not that trivial as it turned out. You cannot really get two positions in sync, even with requestAnimationFrame. Because once you query the host position — it triggers a layout recalculation. So by the time the next frame comes and drop-down is positioned — the host already changes location a little bit. This causes visible jumps, even on fast machines. We got around that by using absolute positioning, rather than fixed. Because the portal container wraps the entire page, position values stay the same during scroll. If the host is in a fixed container, though, it would still jump. But we can detect that when we open the drop-down and use fixed positioning for it as well.

And then there's this:

If the host leaves the visible area — we need to close the drop-down. That's a job for Obscured service. It detects when the host is fully obscured by anything and closes drop-down in that case.

Dialogs

For dedicated portals study we can take a look at dialogs. Toast notifications and hints are very similar but there are some interesting topics to discuss with modals.

This is how dialog host looks like:

<section
   *ngFor="let item of dialogs$ | async"
   polymorpheus-outlet
   tuiFocusTrap
   tuiOverscroll="all"
   class="dialog"
   role="dialog"
   aria-modal="true"
   [attr.aria-labelledby]="item.id"
   [content]="item.component"
   [context]="item"
   [@tuiParentAnimation]
></section>
<div class="overlay"></div>

Instead of being a generic host it has an ngFor loop over particular items. This allows us to bundle some logic in, like focus trap and page scroll blocking. There is also a clever use of dependency injection here, allowing dialogs to be design and data model agnostic. Host collects observables with dialogs through a dedicated multi token, merges these streams and shows the result. That way you can have multiple designs for dialogs in the same app. Taiga UI has two built-in designs — base and mobile. But you can easily add your own. Let's see how.

Dialog service returns Observable. When you subscribe to it, modal popup is shown, when you terminate subscription it is closed. Dialog can also send back data through that stream. First, we design our dialog component. All that's important here, really, is that you can inject POLYMORPHEUS_CONTEXT in constructor. It would contain an object with content and observer for a particular dialog instance. You can close dialog from within by calling complete on observer and you can send back data using next method. Plus all the options you will provide to the service that we will create by extending an abstract class:

const DIALOG = new PolymorpheusComponent(MyDialogComponent);
const DEFAULT_OPTIONS: MyDialogOptions = {
  label: '',
  size: 's',
};

@Injectable({
  providedIn: 'root',
})
export class MyDialogService extends AbstractTuiDialogService<MyDialogOptions> {
  protected readonly component = DIALOG;
  protected readonly defaultOptions = DEFAULT_OPTIONS;
}

In it we provide default config and a component to use and we're all set.

Dialogs, like everything in Taiga UI use ng-polymorpheus for customizable content. You can read more about making interface free, flexible components with it in this article.

Focus trapping is handled by the tuiFocusTrap directive. Since we have drop-downs later in DOM and we can have multiple dialogs open at the same time — we don't care if focus goes farther in the DOM. If it went somewhere prior to dialog though — we return focus back with a few helpers from @taiga-ui/cdk:

@HostListener('window:focusin.silent', ['$event.target'])
onFocusIn(node: Node) {
  if (containsOrAfter(this.elementRef.nativeElement, node)) {
    return;
  }

  const focusable = getClosestKeyboardFocusable(
    this.elementRef.nativeElement,
    false,
    this.elementRef.nativeElement,
  );

  if (focusable) {
    focusable.focus();
  }
}

Blocking page scroll is dealt with by combination of a directive and some logic inside the root component. Root just hides scrollbars when a dialog is open, while Overscroll directive takes care of touch and wheel scroll. There's a CSS rule for overscroll behavior. However it's not sufficient. It doesn't help when dialog is small enough that it doesn't have its own scroll. That's why we have a directive with some additional logic stopping scroll if it will happen in some patent node.

Bonus: what else does tui-root do?

As far as portals go — this covers most of it. Let's also take a quick look at what else is bundled with the root component. You saw in the template that it has tui-scroll-controls. These are custom scrollbars that control global scroll. You may have also noticed named content projections like <ng-content select="tuiOverDialogs"></ng-content>. With those you can slide some content in-between layers of Taiga UI if you need. For example, if you run another library for toasts or dialogs and want them properly placed vertically.

It also registers several event manager plugins in the DI. You can read about them in a dedicated article. It is important that TuiRootModule goes after BrowserModule so they are registered at the right order. But don't worry — if you get it wrong you will see an assertion message in the console.

That wraps it up for portals and the root component. Taiga UI is open-source and you can check it out on GitHub and npm. You can also browse the demo portal with documentation and play with it using this StackBlitz starter. Stay tuned for more articles on interesting features we have!