DEV Community: Taiga UI

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!

Taiga UI is a new Angular UI Kit that you should try

Roman Sedov — Tue, 19 Jan 2021 08:06:23 +0000

Hey, Angular devs!

@waterplea and I write articles about Angular on different blogs from time to time. We wrote almost all of them based on our experience of developing a big UI component library. We've been developing, refactoring and growing it for several years and testing our ideas on a big number of projects in our company.

We are happy to announce that we published our library into open source!

In this article I want to write about concepts and practices that we build our library with and tell you why you should try it for both new and old projects even with other components or UI libraries.

Completely modular

Let’s start with project organization. Taiga UI includes several layers of abstractions as separate packages.

@taiga-ui/cdk

It is a fundamental package. There are many Angular directives, services, tokens, base classes and utils for more safe, abstract and easy work with Angular. This package can be used as an additional multi-tool for your Angular application of any complexity. It can be also a basis for creating your own UI Kit.

Examples of entities:

TuiDestroyService to simplify “destroy$” subjects in components
TuiFilterPipe and TuiMapperPipe to handle values in a template without extra ChangeDetection cycles
tuiPure decorator to memoize getters or class methods

Our “cdk” is different from “@angular/cdk”. It is not a problem to use both of them, because it is not alternative, but addition

@taiga-ui/core

This package includes basic components for building an interface and some tools to make apps easier. Here you can find things like root components, portals for dialogs and dropdowns, theming and animations. Core is a foundation for other packages with UI components. Design and common styles start here.

@taiga-ui/kit

It is a large package that includes many components for building any interface. There are both simple components like avatar, tag or toggle and also composite as for example an input date component that is built with three basic components: textfield with a mask, dropdown and calendar.

@taiga-ui/addon-*

Addons are several thematic packages that are built with cdk, core and kit. There are for example charts package, commerce package for working with currencies, money and card input. There is also a specific doc package that give tools to build your own demo portal as ours (the link will be below 🙂)

We have the following structure with high-level packages built with base packages:

Here comes an important question: why do I need to install several packages as dependencies if I only need a couple of components? What is their size?

Well, we rewrote the structure of our libraries a few months ago. We moved all our packages to the Secondary Entry Points concept.

But we also needed to keep the previous API of imports from the root of the package. That is why we built it in a unique way where every folder deeper is a Secondary Entry Point for the folder higher.

Now all our packages give an opportunity to import entities both from Primary Entry Point and any level of depth.

By the way, the first option is sufficient because nesting can be solved by builder automatically. You do not need to think about depth of import.

This way of organization give us many benefits as:

Application bundle is smaller because all libraries become fully-treeshakable
Any cyclic dependencies can be catched on library building stage
The project is structurized better, there are no extra bindings between its entities

This means that you can import even just one entity from our library and be sure that there is no redundant code in your bundle. There is no code duplication or excess dependencies.

Customizable

All styles and colors of our library are built with CSS custom properties. It allows making new custom themes easy and you can change them on the fly.

Now we offer one main theme of Taiga UI but we have plans to create several simple and several unusual themes.

If you want to customize a single component, there are also some methods to do that. In theory, you can redesign our Kit for your design system in a few hours and use it without worrying because we don’t make breaking changes in CSS-variables too to prevent layout bugs. For example, our company is already using a separate proprietary theme on top of the open source code.

Agnostic

We want to make our components so that every developer could adjust it for their specific case fast and easy.

We do not try to envision every use case. Instead, we do not restrict appearance and use generics so components are not limited to a particular data model. You can read more about such concepts in the article by Alex Inkin “Agnostic components in Angular”.

Nevertheless, we take care of basic UX aspects to let you focus on your project features. For example, when the user focuses our textfield with a keyboard, it will show a hint after a second automatically to let the screen reader read it.

Well engineered

We respect the best developer practices and try to follow the Angular way in development of our libraries.

We are not afraid of DI, all our components use OnPush and the whole project is developed with strict TypeScript mode (we are very sensitive about typings). If you want to use SSR one day, our components will work correctly.

You do not need to worry about unexpected values of wrong types from our components or utils. Our components even print asserts in dev mode if you pass incorrect data to them :)

Read more Angular tips & tricks in my twitter: @marsibarsi

It’s big!

We have 130+ components, 100+ directives, dozens of tokens, utils and tools.

Right now you can build almost any idea of your interface quickly. And it isn't over yet: we have some ideas of next components and we are open to your requests.

How to start using Taiga

Visit our official website with documentation. Here you can see a demo of our components, learn about our libraries and find instructions how to add it into your project: taiga-ui.dev

If you want to support us or see our progress, give a star and follow Taiga UI on Github. There you can ask any questions, propose an idea or contribute to our code.

We also have a channel in Angular discord. Feel free to contact us there!

It's not goodbye

We want to write more articles about how we organize and develop our libraries. Such articles can help you understand better how our UI Kit works. They will also explain all our tricks and practices of developing easy reusable components on Angular that are very helpful in application development too.

Tell us your opinion about Taiga UI and share your ideas about which components, tools or processes you want to read first