Библиотека компонентов на Angular: всё совсем не страшно

Во фронтенд-разработке довольно быстро возникает вопрос: как всё оформить удобно, красиво и единообразно? Сначала всё кажется очевидным – документация показывает, как создать базовый building block, компонент, а дальше чередуй ими и жонглируй, как душе угодно. Более того, можно сильно сэкономить время, используя готовые UI-библиотеки, в которые уже вложены десятки человеко-часов. Но, по мере поступления всё новых задач, порой встают вопросы, которые в какой-то момент побуждают к написанию своего собственного UI Kit.

Сначала это может показаться сложным, муторным, ещё и нужно довольно хорошо разбираться в используемом техстеке. У Angular, например, есть репутация громоздкого фреймворка: не самая очевидная документация, не особо широкое сообщество и меньшая популярность по сравнению с React. На деле всё не так страшно. Angular активно изменяется и улучшается, притом, как и раньше, предоставляя всё необходимое для построения реактивных web-приложений.

Я считаю, что разработка собственной библиотеки компонентов на Angular – это не подвиг, совершённый «вопреки», но вполне разумный инженерный выбор, если подойти к этой задаче последовательно.

Эта статья – скорее, обзор и практическое руководство от «зачем» до «как», с примерами и решениями.

А как же готовое?

Может показаться странным вообще заниматься написанием своего UI Kit, когда уже существует множество зрелых и качественных библиотек. Автор явно не страдает синдромом NIH. Действительно, есть из чего выбрать: Taiga UI ^[1], PrimeNG ^[2], Angular Material ^[3] от того же Google, наконец.

Так почему же всё-таки может возникнуть необходимость разработать свой собственный UI Kit?

1. В библиотеке может не оказаться того базового компонента, что нужно многократно переиспользовать. Хотели сэкономить время, но теперь приходится либо создавать Issue/CR/PR авторам и ждать, надеясь на то, что это будет добавлено в принципе, либо же делать самому

2. Библиотека может не поддерживать или с задержкой внедрять новые возможности фреймворка

3. Проект может в какой-то момент вовсе перестать развиваться, что будет «костью в горле», когда встанет вопрос о переходе на новые версии Angular

4. Некоторые библиотеки подтягивают сторонние зависимости, которые могут быть несовместимы с вашим проектом или не устраивать вас по каким-то иным причинам

5. Компоненты могут не поддерживать какие-то необходимые вам возможности – например, доступность (A11Y) или тёмную тему (Dark Mode)

6. В некоторых библиотеках (не будет показывать пальцем на PrimeNG) темы и стили компонентов настраиваются только через отдельные инструменты, причём платно. Из-за этого ручная настройка стилей может быть если не невозможной, то весьма трудоёмкой

7. В какой-то момент вам может потребоваться добавить функциональность в сторонний компонент, который, будучи нерасширяемым, придётся форкать и переписывать на свой лад

Если вы всё же, осознавая эти ограничения, решились на разработку своего UI Kit, то важно понимать, что именно вам требуется и какие подводные камни могут встретиться на пути.

---

Создание библиотеки и её базовая конфигурация

Что используем?

Есть два основных способа для разработки UI-библиотек на Angular:

1. Официальный, с помощью Angular CLI. Это предполагает создание Workspace – общего пространства для проектов (аналог Solution в мире .NET). Но если в Workspace есть библиотека и приложение, которое её использует, связать их напрямую будет весьма нетривиально

2. Использование Nx ^[4] и его монорепозиториев. Здесь проще управлять зависимостями и связью между библиотеками и приложениями, однако, обратной стороной медали является изучение этого самого Nx

В данной статье мы пойдём по простому и официальному пути – с Angular CLI и отдельным репозиторием под один пакет. Монорепозитории нужны скорее тогда, когда у библиотеки много разных пакетов, публикуемых по отдельности.

Итого:

• Используем Angular CLI

• Создаём отдельный репозиторий под библиотеку

• В нём – Angular Workspace с одним проектом, нашим UI Kit

• Библиотека будет публиковаться в NPM Registry (публичном или корпоративном по типу Nexus или Verdaccio)

Генерация и настройка

Обратимся к официальной документации фреймворка ^[5] и подготовим проект для последней стабильной версии Angular (на момент написания статьи это v19, а выходящая в мае 2025 года v20 ещё будет нуждаться в патчах):

$ npx @angular/cli@19 new ui-repo --no-create-application
$ cd ./ui-repo/
$ npm run ng generate library @my/ui-kit

Теперь библиотека будет доступна как @my/ui-kit. Название можно изменить позже, если потребуется.

В проекте вы можете заметить не один, но два package.json: один в корне проекта, а другой в /projects/my/ui-kit/. Первый относится ко всему Workspace, а второй к самой библиотеке. Любые зависимости устанавливаются обычно, через npm i, глобально для всего Workspace.

Вот пример содержимого /projects/my/ui-kit/package.json:

{
  "name": "@my/ui-kit",
  "version": "0.0.1",
  "peerDependencies": {
    "@angular/common": "^19.2.0",
    "@angular/core": "^19.2.0"
  },
  "dependencies": {
    "tslib": "^2.3.0"
  },
  "sideEffects": false
}

Пояснение:

1. name – это под каким именем пакет будет публиковаться в NPM Registry

2. version – версия пакета. Её следует обновлять перед каждой публикацией, в противном случае вы получите ошибку, поскольку перезапись существующих артефактов недопустима

3. peerDependencies – с какими версиями @angular/* библиотек (но и не только) совместим пакет

4. dependencies – транзитивные зависимости, которые попадут в production

5. sideEffects – флаг для сборщиков, вроде WebPack или Vite, чтобы можно было применять tree-shaking

Можно расширить диапазон поддерживаемых версий Angular, чтобы при обновлении версии фреймворка вам не пришлось сначала обновлять её в библиотеке, публиковать её, а потом проводить тоже самое уже для приложения:

{
  "name": "@my/ui-kit",
  "version": "0.0.1",
  "peerDependencies": {
    "@angular/common": ">=19.2.0 <21.0.0",
    "@angular/core": ">=19.2.0 <21.0.0"
  },
  "dependencies": {
    "tslib": "^2.3.0"
  },
  "sideEffects": false
}

Теперь библиотека будет совместима с Angular 19.2.0 и до 21.0.0 (не включительно).

Обновление версий пакета

Чтобы было удобнее обновлять версию, добавим скрипты в корневой package.json:

{
  "name": "ui-repo",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build --configuration production @my/ui-kit",
    "watch": "ng build --watch --configuration development @my/ui-kit",
    "test": "ng test",
    "release:patch": "cd ./projects/my/ui-kit/ && npm version patch",
    "release:minor": "cd ./projects/my/ui-kit/ && npm version minor",
    "release:major": "cd ./projects/my/ui-kit/ && npm version major"
  },
  "private": true,
  "dependencies": {
    // ...
  },
  "devDependencies": {
   // ...
  }
}

Таким образом, при вызове скриптов у нас будет модифицироваться версия в /projects/my/ui-kit/package.json согласно semantic versioning ^[6]:

$ npm run release:patch # 0.0.1 -> 0.0.2
$ npm run release:minor # 0.0.2 -> 0.1.0
$ npm run release:major # 0.1.0 -> 1.0.0

Если вы не хотите, чтобы вместе с этим ставился и тэг на коммите в git-репозитории, добавьте флаг --no-git-tag-version.

Экспортируемое для использования

Файл public-api.ts определяет, какие сущности доступны извне для использования. По-умолчанию он имеет следующее содержимое:

/*
 * Public API Surface of ui-kit
 */

export * from './lib/ui-kit.service';
export * from './lib/ui-kit.component';

Лучше нам подправить его, чтобы экспортировалось всё из конкретных директорий (компоненты, директивы, сервисы, типы и так далее).

Сперва подкорректируем структуру проекта примерно следующим образом:

/ui-repo/
├── README.md
├── angular.json
├── package-lock.json
├── package.json
├── projects
│   └── my
│       └── ui-kit
│           ├── README.md
│           ├── ng-package.json
│           ├── package.json
│           ├── src
│           │   ├── lib
│           │   │   ├── components
│           │   │   │   ├── index.ts
│           │   │   │   └── ui-kit
│           │   │   │       ├── index.ts
│           │   │   │       ├── ui-kit.component.spec.ts
│           │   │   │       └── ui-kit.component.ts
│           │   │   └── services
│           │   │       ├── index.ts
│           │   │       └── ui-kit
│           │   │           ├── index.ts
│           │   │           ├── ui-kit.service.spec.ts
│           │   │           └── ui-kit.service.ts
│           │   └── public-api.ts
│           ├── tsconfig.lib.json
│           ├── tsconfig.lib.prod.json
│           └── tsconfig.spec.json
└── tsconfig.json

Тогда public-api.ts станет таким:

/*
 * Public API Surface of ui-kit
 */

export * from './lib/components';
export * from './lib/services';

Теперь мы можем начать разрабатывать наш первый компонент.

О компонентах

Standalone vs NgModule

Компоненты – это основа любого современного UI. Они есть в React, Vue и, конечно в Angular. Однако, чтобы раньше использовать компонент, нужно было обязательно его объявить частью NgModule, без которых нельзя было ступить и шагу. Но с v14 всё упростилось: компонент, директива или пайп могут быть не привязаны к NgModule (так называемые Standalone). Мы будем использовать этот же подход.

Если вы ранее работали со сторонними UI-библиотками для Angular, то, возможно, замечали: в некоторых каждый компонент подключается через свой NgModule. Это так называемый «SCAM-паттерн ^[7]» (Single Component Angular Module). Его придумали, чтобы улучшить работу tree-shaking: подключаешь только то, что нужно, а не один-единственный модуль, который поставляет вообще всё. И размер итоговой сборки уменьшается.

С появлением Standalone-компонентов и необходимость в таком, скажем откровенно, костыле, как SCAM-паттерн, отпала, а компоненты можно использовать без лишних обёрток.

В Angular есть два основных подхода к созданию компонентов. Рассмотрим каждый из них

Компонент со стандартным селектором

Обычный способ: создаём компонент со своими стилями и логикой, а Angular вставляет его в DOM-дерево, как отдельный HTML-элемент.

Например такой компонент:

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

@Component({
  selector: 'lib-ui-kit',
  template: `
    <p>
      ui-kit works!
    </p>
  `,
})
export class UiKitComponent {}

При использовании в шаблоне будет выглядеть так:

<lib-ui-kit>
  <p>
    ui-kit works!
  </p>
</lib-ui-kit>

Компонент с нестандартным селектором/директива

Можно задать поле selector декоратора @Component в виде атрибута или псевдокласса, чтобы наш компонент оказался «нанизан» на обычный HTML-элемент, выступающий скелетом (host-элементом).

Например, вот такой компонент:

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

@Component({
  selector: '[framed-image]',
  templateUrl: './framed-image.component.html',
})
export class FramedImageComponent { ... }

В шаблоне можно применить так:

<div
  framed-image="art-deco"
  src="somePainting.jpg"
/>

Выглядит, конечно, странно. Но именно так можно добиться максимально семантической вёрстки.

А в чём разница?

Мы привыкли считать, что компонент – это просто HTML-шаблон вместе с code-behind. Но стоит взглянуть в DevTools, то станет ясно: Angular оборачивает каждый компонент в host-элемент, что не всегда удобно.

Рассмотрим пример с Bootstrap Navbar. Например, вот такой шаблон:

<ul class="navbar-nav mr-auto">
  <li class="nav-item active">
    <a class="nav-link" href="#">
      Home <span class="sr-only">(current)</span>
    </a>
   </li>

   <li class="nav-item">
     <a class="nav-link" href="#">
      Link
    </a>
   </li>
</ul>

Решив декомпозировать это на Angular-компоненты, мы можем описать структуру при помощи компонентов Navbar и Navlink вот так:

<navbar>
  <navlink [active]="true" href="#">
    Home <span class="sr-only">(current)</span>
  </navlink>

  <navlink [active]="false" href="#">
    Link
  </navlink>
</navbar>

Однако, в DOM-дереве это превратится в:

<navbar>
  <ul class="navbar-nav mr-auto">
    <navlink>
      <li class="nav-item active">
        <a class="nav-link" href="#">
          Home <span class="sr-only">(current)</span>
        </a>
      </li>
    </navlink>

    <navlink>
      <li class="nav-item">
        <a class="nav-link" href="#">
          Link
        </a>
      </li>
    </navlink>
  </ul>
</navbar>

По итогу мы получаем лишние уровни вложенности, которые нам мало того, что усложняют стили и ломают семантическую вёрстку, так, вместе с ними, ещё и A11Y. И это ещё полбеды.

По-умолчанию, host-элемент, если он используется как обычный селектор, имеет display: inline. Это может вызвать неожиданные проблемы, если вам нужно точно рассчитать размер или позицию компонента, например, чтобы показать tooltip. Хоть это не влияет на рендеринг и поведение приложения, но такой host-элемент не совпадает по размеру с содержимым, которое он оборачивает. И наш tooltip по итогу окажется не там, где вы ожидали...

Если сравнить оба подхода:

Какой подход выбирать – зависит от решаемой задачи. В данной статье мы рассмотрим компонент, который вряд ли можно реализовать без использования стандартного селектора – иконку.

Создание компонента

Проектирование, разработка, ассеты

Иконки чаще всего делают в виде SVG, изображений или кастомных шрифтов с CSS. Мы выберем SVG – это золотая середина между гибкостью и простотой.

Что нужно от иконок в библиотеке:

1. Иконки – это SVG

2. Все иконки имеют квадратные пропорции

3. При повторном использовании иконка загружается по сети только один раз

4. Все иконки предустановлены в библиотеку, а не ссылаются на какой-то CDN

Учитывая упомянутое, получим такой пример компонента иконки:

import {
  ChangeDetectionStrategy,
  Component,
  computed,
  inject,
  input,
} from '@angular/core';

import { IconLoaderService } from '../services';

/**
 * SVG-иконка, отображаемая на экране
 */
@Component({
  selector: 'lib-ui-icon',
  template: `
    <svg
      [attr.width]="size()"
      [attr.height]="size()"
    >
      <use [attr.href]="iconLocation()"></use>
    </svg>
  `,
  styles: `
    :host {
      display: flex;
    }
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class IconComponent {
  /** Имя иконки */
  public readonly name = input<string>('');

  /** Размер иконки (px). По-умолчанию, `24` */
  public readonly size = input<number>(24);

  private readonly iconLoader = inject(IconLoaderService);

  /** Местоположение иконки */
  protected readonly iconLocation = computed<string>(() => {
    const iconName = this.name();
    return this.iconLoader.loadBuiltInIcon(iconName);
  });
}

Чтобы всё заработало, нам необходимо обеспечить подгрузку ассетов и их наличие в итоговой сборке. Angular позволяет включить их в библиотеку: нужно лишь указать путь к ним в файле ng-package.json.

Для начала уберём сгенерированные при создании библиотеки Angular CLI компонент с сервисом, а также добавим директорию /assets/. Думаю, вместо того, чтобы подгружать каждый отдельный SVG по сети, а также поставлять их в таком виде в библиотеке, можно их объединить в отдельные спрайты по группам, причём отделим чёрно-белые от цветных.

Тогда в библиотеке структура станет следующей:

/ui-repo/
├── README.md
├── angular.json
├── package-lock.json
├── package.json
├── projects
│   └── my
│       └── ui-kit
│           ├── README.md
│           ├── ng-package.json
│           ├── package.json
│           ├── src
│           │   ├── assets
│           │   │   └── icons
│           │   │       ├── colorful
│           │   │       │   ├── brands.svg
│           │   │       │   └── countries.svg
│           │   │       └── monochrome
│           │   │           ├── brands.svg
│           │   │           └── common.svg
│           │   ├── lib
│           │   │   └── components
│           │   │       ├── icon
│           │   │       │   ├── components
│           │   │       │   │   ├── icon.component.ts
│           │   │       │   │   └── index.ts
│           │   │       │   └── index.ts
│           │   │       └── index.ts
│           │   └── public-api.ts
│           ├── tsconfig.lib.json
│           ├── tsconfig.lib.prod.json
│           └── tsconfig.spec.json
└── tsconfig.json

А файл ng-package.json из изначально такого:

{
  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
  "dest": "../../../dist/my/ui-kit",
  "lib": {
    "entryFile": "src/public-api.ts"
  }
}

Станет таким:

{
  "$schema": "../../../node_modules/ng-packagr/ng-package.schema.json",
  "dest": "../../../dist/my/ui-kit",
  "lib": {
    "entryFile": "src/public-api.ts"
  },
  "assets": [
    "src/assets"
  ]
}

Теперь при сборке (npm run build) ассеты окажутся доступны по пути /dist/my/ui-kit/src/assets/.

Подключение SVG через спрайты

Спрайты устроены следующим образом – это отдельный SVG-файл, содержащий набор <symbol>, каждый с уникальным id. Мы можем сослаться на эти id и использовать их при помощи <use> в нашем IconComponent.

Например, содержимого /monochrome/brands.svg может иметь следующий вид:

<svg height="0" width="0" xmlns="http://www.w3.org/2000/svg" focusable="false">
  <symbol id="mc__brands__telegram" viewBox="0 0 24 24">
    <g>
      <path fill="currentColor" d="..." />
    </g>
  </symbol>
  <symbol id="mc__brands__google" viewBox="0 0 24 24">
    <g>
      <path fill="currentColor" d="..." />
    </g>
  </symbol>
</svg>

Теперь реализуем IconLoaderService, который загружает нужный спрайт только один раз, вставляет его в DOM и возвращает ссылку на иконку (наверняка, существует реализация и лучше, о чём вы маякнёте в комментариях):

import { inject, Injectable, SecurityContext } from '@angular/core';
import { DOCUMENT } from '@angular/common';
import { HttpClient, HttpHeaders } from '@angular/common/http';
import { DomSanitizer } from '@angular/platform-browser';

import { map, Observable, take, tap } from 'rxjs';

import { IconsMeta } from '../types';

/**
 * Сервис для подгрузки иконок
 */
@Injectable({ providedIn: 'root' })
export class IconLoaderService {
  private readonly httpClient = inject(HttpClient);
  private readonly sanitizer = inject(DomSanitizer);
  private readonly document = inject(DOCUMENT);

  /** Метаданные по цветным иконкам */
  private readonly COLORFUL_ICONS_META: IconsMeta = {
    prefix: 'clr',
    directory: 'colorful',
    sprites: [
      'brands',
      'countries',
    ],
  };

  /** Метаданные по монохромным иконкам */
  private readonly MONOCHROME_ICONS_META: IconsMeta = {
    prefix: 'mc',
    directory: 'monochrome',
    sprites: [
      'brands',
      'common',
    ],
  };

  /** Разделитель в именах иконок */
  private readonly NAME_DELIMITER = '__';

  /**
   * Загрузить поставляемую библиотекой иконку
   *
   * @param name - Имя иконки по формуле `<PREFIX>__<SPRITE>__<NAME>`
   * @returns Относительный путь к иконке, если имя иконки соответствует формуле; иначе `''`. Наличие самой иконки по пути не проверяется
   */
  public loadBuiltInIcon(name: string): string {
    const isNameValid = this.isIconNameValid(name);
    if (!isNameValid) {
      return '';
    }

    const nameParts = name.split(this.NAME_DELIMITER);
    const prefix = nameParts[0];
    const sprite = nameParts[1];
    let directory = '';

    switch (prefix) {
      case this.COLORFUL_ICONS_META.prefix: {
        directory = this.COLORFUL_ICONS_META.directory;
        break;
      }

      case this.MONOCHROME_ICONS_META.prefix: {
        directory = this.MONOCHROME_ICONS_META.directory;
        break;
      }

      default: {
        break;
      }
    }

    const iconPath = `#${name}`;
    const spriteId = `svg__${prefix}__${sprite}`;

    // Проверяем, подгружены ли спрайты в DOM-дерево страницы, откуда их можно потом извлечь.
    // В случае отсутствия, подгружаем и размещаем в дереве в отдельных скрытых div-элементах
    const spriteBlock = this.document.getElementById(spriteId);
    if (!spriteBlock) {
      this.loadIconSprite(spriteId, directory, sprite).subscribe();
    }

    return iconPath;
  }

  /**
   * Загрузить спрайт с группой иконок
   *
   * @param id - Уникальный идентификатор, под которым будет зарегистрирована загруженная группа иконок
   * @param sprite - Имя группы иконок
   * @returns `Observable` с сигналом об успешной загрузке спрайта
   */
  private loadIconSprite(id: string, directory: string, sprite: string): Observable<void> {
    // Располагаем группу иконок в скрытом div, из него же и будет осуществляться подгрузка локально
    const spriteBlock = this.document.createElement('div');
    spriteBlock.setAttribute('id', id);
    spriteBlock.style.height = '0';
    spriteBlock.style.width = '0';
    this.document.body.insertBefore(spriteBlock, this.document.body.firstChild);

    const spriteUrl = `public/icons/${directory}/${sprite}.svg`;

    return this.httpClient.get(`${window.location.origin}/${spriteUrl}`, {
        headers: new HttpHeaders().set('accept', 'image/svg+xml'),
        responseType: 'text'
      })
      .pipe(
        take(1),
        tap((response) => {
          spriteBlock.innerHTML = this.sanitizer.sanitize(
            SecurityContext.HTML,
            this.sanitizer.bypassSecurityTrustHtml(response),
          ) as string;
        }),
        map(() => undefined),
      );
  }

  /**
   * Совпадает ли имя иконки согласно формуле `<PREFIX>__<SPRITE>__<NAME>` с определёнными типами и группами иконок
   *
   * @param name - Имя иконки
   * @returns `true`, если имя совпадает; иначе `false`
   */
  private isIconNameValid(name: string): boolean {
    const nameParts = name.split(this.NAME_DELIMITER);

    // Любая встроенная иконка должна иметь имя из 3-х компонент
    if (nameParts.length < 3) {
      return false;
    }

    // Первая компонента должна указывать на тип иконки
    const iconType = nameParts[0];
    if (iconType !== this.COLORFUL_ICONS_META.prefix && iconType !== this.MONOCHROME_ICONS_META.prefix) {
      return false;
    }

    // Вторая компонента должна быть одной из доступных групп
    const iconGroup = nameParts[1];
    if (
      (iconType === this.COLORFUL_ICONS_META.prefix && !this.COLORFUL_ICONS_META.sprites.includes(iconGroup))
      || (iconType === this.MONOCHROME_ICONS_META.prefix && !this.MONOCHROME_ICONS_META.sprites.includes(iconGroup))
    ) {
      return false;
    }

    return true;
  }
}

Готово. Но неплохо было бы и проверить как оно работает на деле.

Тестирование

Инструменты

При разработке библиотеки нам не обойтись без тестирования. В нашем случае, нам нужны:

1. Test runner, который можно будет запустить как локально, так и на этапе CI/CD. Вместо безнадёжно устаревшей Karma, с которой ещё и приходится извращаться, воспользуемся Jest

2. Playground для витрины компонентов и визуального тестирования. Из вариантов: StoryBook ^[8] и NgDoc ^[9]. С последним, увы, здесь не получится так просто сделать, потому что он требует отдельное приложение. StoryBook не является более лучшим кандидатом, тем не менее, его будет для нас более, чем достаточно (хоть и придётся бороться с его React-ориентированностью)

Подключаем Jest

Пока официальных и стабильных сборок от команды Angular с новым test runner нет, но не беда. Достаточно воспользоваться jest-preset-angular ^[10].

Устанавливаем зависимости:

$ npm uninstall @types/jasmine jasmine-core karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter
$ npm i -D jest jest-preset-angular @types/jest ts-node

Создаём конфигурацию jest.config.ts в корне, сразу же с code coverage:

import type { Config } from 'jest';
import { createCjsPreset } from 'jest-preset-angular/presets';

const config: Config = {
  ...createCjsPreset(),
  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
  rootDir: './projects/my/ui-kit',
  collectCoverage: true,
  coverageDirectory: '<rootDir>/../../../coverage',
  coverageReporters: [
    'clover',
    'json',
    'lcov',
    'html'
  ]
};

export default config;

Файл инициализации окружения /projects/my/ui-kit/jest.setup.ts:

import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';

setupZoneTestEnv();

// Define global Mocks below

Конфигурацию для Typescript в /projects/my/ui-kit/tsconfig.spec.json:

{
  "extends": "../../../tsconfig.json",
  "compilerOptions": {
    "outDir": "../../../out-tsc/spec",
    "module": "ES2022",
    "types": ["jest"]
  },
  "include": [
    "src/**/*.spec.ts",
    "src/**/*.d.ts"
  ]
}

А также скрипты для запуска в корневом package.json для 3-х случаев:

1. Тестирование локально с однократным запуском (npm run test)

2. Тестирование локально с watch-режимом (npm run test:watch)

3. Тестирование на сборочном агенте на этапе CI/CD (npm run test:ci)

{
  "name": "ui-repo",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build --configuration production @my/ui-kit",
    "watch": "ng build --watch --configuration development @my/ui-kit",
    "test": "jest --maxWorkers=50%",
    "test:ci": "jest ---detectOpenHandles",
    "test:watch": "jest --watch --detectOpenHandles"
  },
  "private": true,
  "dependencies": {
    // ...
  },
  "devDependencies": {
    // ...
  }
}

Теперь просто попробуем прогнать самый простой тест следующего содержания:

import { ComponentRef } from '@angular/core';
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { provideHttpClient } from '@angular/common/http';
import { provideHttpClientTesting } from '@angular/common/http/testing';

import { IconComponent } from './icon.component';

describe('Icon', () => {
  let component: IconComponent;
  let componentRef: ComponentRef<IconComponent>;
  let fixture: ComponentFixture<IconComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [
        IconComponent,
      ],
      providers: [
        provideHttpClient(),
        provideHttpClientTesting(),
      ],
    }).compileComponents();

    fixture = TestBed.createComponent(IconComponent);
    component = fixture.componentInstance;
    componentRef = fixture.componentRef;

    fixture.detectChanges();
  })

  it('Компонент создаётся', () => {
    expect(component).toBeTruthy();
  });
});

И результаты:

$ npm run test

> ui-repo@0.0.0 test
> jest --maxWorkers=50%

 PASS  projects/my/ui-kit/src/lib/components/icon/components/icon.component.spec.ts
  Icon
    √ Компонент создаётся (72 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.195 s, estimated 9 s
Ran all test suites.

StoryBook

StoryBook далеко не идеальный инструмент из-за своей React-ориентированности, но в роли песочницы для тестирования компонентов и витрины вполне подойдёт.

Установка и конфигурация максимально проста:

$ npm create storybook@latest

Рекомендуется согласится на использование compodoc – так вы получите автоматическую документацию, составленную из ваших JSDoc-комментариев.

StoryBook нам потребуется также подготовить, чтобы он знал о наших иконках и других ассетах. Для этого отредактируем /projects/my/ui-kit/.storybook/main.ts следующим образом:

import type { StorybookConfig } from '@storybook/angular';

const config: StorybookConfig = {
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-onboarding',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: "@storybook/angular",
    options: {}
  },
  staticDirs: [
    {
      from: '../src/assets',
      to: '/public',
    }
  ]
};

export default config;

Для корректной работы Angular-компонентов, требуется определить метаданные, подгружаемые в StoryBook:

import { provideHttpClient } from '@angular/common/http';

import { applicationConfig } from '@storybook/angular';

/**
 * Метаданные для настройки конфигурации StoryBook
 */
export const StorybookModuleMeta = [
  applicationConfig({
    providers: [
      provideHttpClient(),
    ],
  }),
];

Остаётся лишь Story. Это такая сущность, которая позволит нам подготовить полигон для тестирования компонента, предварительно передав ему значения input(). Определим их две: пускай одна будет playground, а другая просто отображает все доступные иконки:

import { StoryObj, Meta } from '@storybook/angular';

import { StorybookModuleMeta } from '../../../../storybook-meta';
import { IconComponent } from '../components';

const meta: Meta<typeof IconComponent> = {
  title: 'Components/Icon',
  component: IconComponent,
  decorators: StorybookModuleMeta,
  parameters: {
    controls: {
      exclude: ['iconLocation'],
    },
  },
};

export default meta;

type Story = StoryObj<IconComponent>;
type UntypedStory = StoryObj;

export const Playground: Story = {
  args: {
    name: 'mc__common__cog',
    size: 24,
  },
};

export const AvailableIcons: UntypedStory = {
  render: () => ({
    template: `
      <div style="display: flex; flex-direction: column; margin: 1rem; width: 400px; height: 400px;">
        <div style="display: flex; justify-content: space-between; margin-bottom: 1rem;">
          <lib-ui-icon name="mc__brands__telegram" />
          <lib-ui-icon name="mc__brands__github" />
          <lib-ui-icon name="mc__brands__google" />
          <lib-ui-icon name="mc__common__bolt" />
          <lib-ui-icon name="mc__common__cog" />
          <lib-ui-icon name="mc__common__document" />
        </div>

        <div style="display: flex; justify-content: space-between">
          <lib-ui-icon name="clr__brands__windows" />
          <lib-ui-icon name="clr__brands__apple" />
          <lib-ui-icon name="clr__brands__android" />
          <lib-ui-icon name="clr__countries__germany" />
          <lib-ui-icon name="clr__countries__iceland" />
          <lib-ui-icon name="clr__countries__russia" />
        </div>
      </div>
    `,
  })
}

Можем оценить результаты, запустив StoryBook:

Кастомные настройки

Допустим, нас устраивает текущая реализация нашего компонента. Но что если потребуются немного иные условия, в которых работает приложение – например, для него определён base HREF? В таком случае, жёстко прописанные пути к ассетам, как в IconLoaderService, уже не подойдут.

Здесь нам поможет InjectionToken ^[11]. Мы создадим токен с настройками, которые можно передать извне и внедрить их в нужные сервисы и компоненты.

Также определим функцию provideUiKitSettings() для внедрения нового объекта настроек – по аналогии с provideHttpClient() и другими:

import { InjectionToken, Provider } from '@angular/core';

/**
 * Структура параметров UI Kit
 */
export type UiKitParams = {
  /** URL, на котором стартует приложение, если от отличается от `/` */
  baseHref: string;

  /** Имя директории, в которой доступны приложению ассеты */
  assetsDirectory: string;
};

/** Параметры UI Kit, передаваемые извне */
export const UI_KIT_PARAMS = new InjectionToken<UiKitParams>('UiKitParams');

/**
 * Предоставить пустую конфигурацию для `@my/ui-kit`
 *
 * @returns Пустая конфигурация для токена `UI_KIT_PARAMS`
 */
export const provideUiKitEmptySettings = (): Provider => {
  const config: UiKitParams = {
    baseHref: '',
    assetsDirectory: ''
  };

  return {
    provide: UI_KIT_PARAMS,
    useValue: config,
  };
};

/**
 * Предоставить конфигурацию для `@my/ui-kit`
 *
 * @param config - Конфигурация библиотеки
 * @returns Заданная конфигурация для токена `UI_KIT_PARAMS`
 */
export const provideUiKitSettings = (config: UiKitParams): Provider => ({
  provide: UI_KIT_PARAMS,
  useValue: config,
});

Почему отдельно ещё вынесен и assetsDirectory? В Angular до v18 ассеты размещались в /assets/, в более поздних версиях в /public/. Плюс, в разных проектах пути вообще могут быть совершенно своими, поэтому лучше оставить это настраиваемым.

Применим эти настройки в IconLoaderService:

import { inject, Injectable, SecurityContext } from '@angular/core';
import { DOCUMENT } from '@angular/common';
import { HttpClient, HttpHeaders } from '@angular/common/http';
import { DomSanitizer } from '@angular/platform-browser';

import { map, Observable, take, tap } from 'rxjs';

import { IconsMeta } from '../types';
import { UI_KIT_PARAMS } from '../../../config';

/**
 * Сервис для подгрузки иконок
 */
@Injectable({ providedIn: 'root' })
export class IconLoaderService {
  // ...
  
  private readonly libParams = inject(UI_KIT_PARAMS);

  // ...

  /**
   * Загрузить спрайт с группой иконок
   *
   * @param id - Уникальный идентификатор, под которым будет зарегистрирована загруженная группа иконок
   * @param sprite - Имя группы иконок
   * @returns `Observable` с сигналом об успешной загрузке спрайта
   */
  private loadIconSprite(id: string, directory: string, sprite: string): Observable<void> {
    // ...

    const spriteUrl = `${this.libParams.assetsDirectory}/icons/${directory}/${sprite}.svg`;
    const baseHref = this.libParams.baseHref.length > 0
      ? `${this.libParams.baseHref}/`
      : '';

    return this.httpClient.get(`${window.location.origin}/${baseHref}${spriteUrl}`, {
        headers: new HttpHeaders().set('accept', 'image/svg+xml'),
        responseType: 'text'
      })
      .pipe(
        take(1),
        tap((response) => {
          spriteBlock.innerHTML = this.sanitizer.sanitize(
            SecurityContext.HTML,
            this.sanitizer.bypassSecurityTrustHtml(response),
          ) as string;
        }),
        map(() => undefined),
      );
  }
}

Не забудьте скорректировать метаданные для StoryBook, прокинув в него нашу provideUiKitSettings() функцию. Иначе он не найдёт наш InjectionToken и ранее работавшие Story сломаются. К тестам это также относится, но для них подойдёт функция provideUiKitEmptySettings().

Отладка в связке с проектом

Тестовая сборка

После всей проделанной работы было бы неплохо опробовать библиотеку в каком-то приложении. Конечно, её можно опубликовать в NPM Registry и подключить, как обычный пакет, но если вдруг при интеграции всплывёт ошибка, чинить её и выпускать отдельный патч будет не особо удобно. Гораздо лучше отлаживать библиотеку локально – и это несложно.

Способ работает как для проектов с WebPack, так и для связки Vite + ESBuild.

Для начала нам необходимо собрать нашу библиотеку в watch-режиме и добавить на неё symlink. Для этого в разных сессиях терминала нам следует выполнить:

$ npm run watch              # Сессия терминала 1: сборка в watch-режиме
$ npm link ./dist/my/ui-kit/ # Сессия терминала 2: создаём symlink на сборку после её завершения

Настройка приложения

Теперь внесём изменения в angular.json нашего приложения:

1. Добавим ассеты, записав в projects.<PROJECT>.architect.build.options.assets следующее:

{
  "glob": "**/*",
  "input": "./node_modules/@my/ui-kit/src/assets/",
  "output": "public" // Или assets, в зависимости от вашего проекта
}

2. В projects.<PROJECT>.architect.build.options добавим:

"preserveSymlinks": true

3. Отключим кэш CLI, чтобы HMR работал корректно:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    // Projects definiton
  },
  "cli": {
    "cache": {
      "enabled": false
    }
  }
}

Связывание

Теперь подключим библиотеку как зависимость:

$ npm link @my/ui-kit

В /node_modules/ у нас появляется ссылка на сборку нашей библиотеки, и при всяком изменении библиотеки, приложение будет подтягивать их и пересобираться.

Далее определим для библиотеки параметры в app.config.ts:

import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideRouter } from '@angular/router';

import { provideUiKitSettings } from '@my/ui-kit';

import { routes } from './app.routes';
import { environment } from '../environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),
    provideHttpClient(),
    provideUiKitSettings({
      baseHref: environment.baseHref,
      assetsDirectory: environment.assetsDirectory,
    })
  ]
};

И для теста попробуем отрендерить тоже самое, что и для нашей Story со всеми иконками:

Как видно, все ассеты подгрузились корректно, притом, что наш environment был определён так:

export const environment = {
  baseHref: '',
  assetsDirectory: 'public',
};

Убедимся в том, что наши настройки передаются и работают корректно. Например, изменим значение baseHref на accounts:

Ассеты не подгружаются по причине изменившегося итогового пути, не совпадающего с тем, где они доступны локально. Поведение точно такое, какое мы и ожидали.

Поддержка форм

Angular Forms – это невероятно мощный пакет для работы со стандартными HTML-формами и их централизованной обработке. Мы можем добавить поддержку форм прямо в наши компоненты, если они реализуют интерфейс ControlValueAccessor.

Несмотря на пугающее название и содержание, здесь всё просто:

• writeValue – вызывается, когда Angular хочет записать значение в FormControl. Это происходит при изменении ngModel в явном виде, либо через форму, к которой привязан FormControl

• registerOnChange – регистрирует callback, который нужно вызывать при изменении значения пользователем, чтобы уведомить об этом форму

• registerOnTouched – регистрирует callback, чтобы сообщить форме, что пользователь взаимодействовал с FormControl (например, кликнул или сфокусировался)

• setDisabledState – сообщает FormControl, нужно ли его отключить

Предположим, мы хотим реализовать трёхпозиционный флажок, checkbox, который будет принимать значения true, false и null. Вот его примерная реализация с поддержкой Angular Forms:

import {
  Component,
  forwardRef,
  signal,
} from '@angular/core';
import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

/**
 * Флажок с тремя состояниями: `true`, `false` и `null`
 */
@Component({
  selector: '...',
  
  // Необходимо указать для регистрации FormControl
  // Это позволит использовать компонент в составе Angular Forms и задействовать [(ngModel)]
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => TriCheckboxComponent),
      multi: true,
    },
  ],
})
export class TriCheckboxComponent implements ControlValueAccessor {
  writeValue(val: boolean | null): void {
    this.ngModelValue.set(val);
  }

  registerOnChange(fn: Function): void {
    this.onModelChange = fn;
  }

  registerOnTouched(fn: Function): void {
    this.onModelTouched = fn;
  }

  setDisabledState(val: boolean): void {
    this.disabled.set(val);
  }

  /** Значение `ngModel` */
  private ngModelValue = signal<boolean | null>(null);

  /** Значение флажка */
  public readonly checkedValue = this.ngModelValue.asReadonly();

  /** Отключён ли компонент */
  private readonly disabled = signal<boolean>(false);

  /** Сообщает форме, что `FormControl` изменил значение (изменяет `ngModel`) */
  private onModelChange: Function = () => {};

  /** Сообщает форме, что `FormControl` был затронут пользователем (ставит CSS-класс `ng-touched` в форме) */
  private onModelTouched: Function = () => {};

  /**
   * Обработка нажатия на флажок
   * 
   * @param event – Сопутствующее событие
   */
  protected clickTriCheckbox(event: Event): void {
    event.preventDefault();

    if (this.disabled()) {
        return;
    }

    this.toggleState();
    this.onModelChange(this.checkedValue());
    this.onModelTouched();
  }

  /**
   * Изменить состояние флажка
   */
  public toggleState(): void {
    // Состояние прогоняется по циклу null-true-false
    switch (this.checkedValue()) {
        case true: {
            this.ngModelValue.set(false);
            break;
        }

        case false: {
            this.ngModelValue.set(null);
            break;
        }

        case null: {
            this.ngModelValue.set(true);
            break;
        }

        default: {
            break;
        }
    }
  }
}

Единственное допущение в части типизации — это обобщённая типизация для callback registerOnTouched и registerOnChange.

Тёмная тема (Dark Mode)

Идея

Сегодня тёмная тема – это уже стандарт. Реализуют её примерно одинаково, но сделаем это с учтом последних возможностей CSS, просто и эффективно:

1. Используем глобальные CSS-переменные, определяющие стили для компонентов и вызываемые через функцию var(). Только учитывайте, что если переменной не будет или в её имени будет опечатка, распознать ошибку вы сможете только в runtime

2. Определим переменные через CSS-функцию light-dark() – это позволяет задать значения для светлой и тёмной темы одновременно

3. С помощью атрибута theme на <html> будем управлять активной темой. Это будет определять значения свойства color-scheme, что выбирает какое значение использовать для функции light-dark()

4. Создадим сервис, который будет переключать тему и сохранять выбор в LocalStorage, чтобы применять её после перезагрузки страницы

5. При старте приложения на этапе APP_INITIALIZER тема будет автоматически подбираться от предпочтений системы (через prefers-color-scheme)

Реализация

Пример CSS-стилей выглядит следующим образом:

/* Набор глобальных переменных для применения в компонентах */
:root {
  --btn-text-color: light-dark(white, rgb(46, 43, 43));
  --btn-background-color: light-dark(rgb(11, 88, 160), rgb(20, 211, 195));
}

/* Светлая цветовая тема: для light-dark() будет применяться первый аргумент */
[theme="light"] {
  color-scheme: light;
}

/* Тёмная цветовая тема: для light-dark() будет применяться второй агрумент /
[theme="dark"] {
  color-scheme: dark;
}

Применим эти стили в компоненте:

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

/**
 * Обычная кнопка
 */
@Component({
  selector: 'button[lib-ui-button]',
  template: `
    <ng-content />
  `,
  styles: `
    :host {
      padding: 10px;
      border: none;
      border-radius: 2px;
      color: var(--btn-text-color);
      background-color: var(--btn-background-color);
    }
  `,
})
export class ButtonComponent {
  // ...
}

Определим enum с темами:

/**
 * Используемая тема оформления
 */
export enum Theme {
  /** Светлая */
  Light = 'light',

  /** Тёмная */
  Dark = 'dark',
}

Далее сервис по переключению тем оформления:

import { inject, Injectable } from '@angular/core';
import { DOCUMENT } from '@angular/common';

import { Theme } from '../../enums';

/**
 * Сервис по настройке темы оформления
 */
@Injectable({ providedIn: 'root' })
export class ThemeService {
  private readonly document = inject(DOCUMENT);

  /** Атрибут в DOM для определения темы оформления */
  private readonly THEME_ATTRIBUTE = 'theme';

  /** Ключ в `LocalStorage`, где записана выбранная тема */
  private readonly STORAGE_KEY = 'ui-theme';

  /**
   * Инициализировать данные по теме оформления
   */
  public initialize(): void {
    const currentTheme = localStorage.getItem(this.STORAGE_KEY) as Theme;
    if (currentTheme) {
      this.applyTheme(currentTheme);
      return;
    }

    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const initialTheme = prefersDark
      ? Theme.Dark
      : Theme.Light;

    this.applyTheme(initialTheme);
  }

  /**
   * Установить выбранную тему оформления
   *
   * @param theme - Тип темы
   */
  public setTheme(theme: Theme): void {
    this.applyTheme(theme);
  }

  /**
   * Переключить тему оформления
   */
  public toggleTheme(): void {
    const currentTheme = localStorage.getItem(this.STORAGE_KEY) as Theme ?? Theme.Light;
    const newTheme = currentTheme === Theme.Light
      ? Theme.Dark
      : Theme.Light;

    this.applyTheme(newTheme);
  }

  /**
   * Применить тему оформления
   *
   * @param theme - Тип темы
   */
  private applyTheme(theme: Theme): void {
    this.document.documentElement.removeAttribute(this.THEME_ATTRIBUTE);
    this.document.documentElement.setAttribute(this.THEME_ATTRIBUTE, theme);
    localStorage.setItem(this.STORAGE_KEY, theme);
  }
}

Тестирование

Чтобы убедиться, что темы работают, проверим это в StoryBook:

1. Добавим вызов инициализации на этапе APP_INITIALIZER в мета-конфигурации:

import { provideHttpClient } from '@angular/common/http';
import { inject, provideAppInitializer } from '@angular/core';

import { applicationConfig } from '@storybook/angular';

import { ThemeService } from './lib/services';
import { provideUiKitSettings } from './lib/config';

/**
 * Метаданные для настройки конфигурации StoryBook
 */
export const StorybookModuleMeta = [
  applicationConfig({
    providers: [
      provideHttpClient(),
      provideUiKitSettings({
        baseHref: '',
        assetsDirectory: 'public',
      }),
      provideAppInitializer(() => {
        const themeSwitcher = inject(ThemeService);
        themeSwitcher.initialize();
      }),
    ],
  }),
];

2. Подключим глобальные стили в angular.json. Для этого добавим путь к стилям в раздел projects.@my/ui-kit.storybook.styles

3. Создадим демонстрационный компонент и Story к нему:

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

import { StoryObj, Meta } from '@storybook/angular';

import { StorybookModuleMeta } from '../../../storybook-meta';
import { ThemeService } from '../../services';
import { ButtonComponent } from './button.component';

@Component({
  selector: 'app-demo',
  template: `
    <button
      lib-ui-button
      (click)="toggle()"
    >
      Toggle theme
  </button>
  `,
  imports: [
    ButtonComponent,
  ]
})
class DemoComponent {
  private readonly themeSwitcher = inject(ThemeService);

  public toggle(): void {
    this.themeSwitcher.toggleTheme();
  }
}

const meta: Meta<typeof DemoComponent> = {
  title: 'Components/Button',
  component: DemoComponent,
  decorators: StorybookModuleMeta,
};

export default meta;

type Story = StoryObj<DemoComponent>;

export const Playground: Story = {};

Результат:

Доступность (A11Y)

Accessibility… Как много боли в этом слове.
Честно, мне не доводилось ещё встречать людей, которые не забивают на него при разработке web-приложений, особенно, если нет прямого запроса со стороны заказчика. Тесты, тоже многими нелюбимые, должно быть, пишет куда больше людей, чем мучает голову A11Y.

Создавая библиотеку компонентов, нам, порой, приходится нарушать банальную HTML-семантику, влияющую на A11Y: например, заворачивать элементы table в компонент для переиспользуемости, городить что-то своё ввиду невозможности кастомизировать вид стандартного <input type="checkbox" /> и так далее. Всё это может серьёзно подорвать доступность – как с точки зрения навигации, так и в контексте взаимодействия с экранными читалками, клавиатурой и прочим.

Angular позволяет сохранить относительное удобство и визуальную гибкость без особого ущерба для A11Y. Вот несколько практических рекомендаций:

1. Используйте нестандартные, атрибутные селекторы, когда это возможно. Так в избегаете лишних обёрток, и не допускаете семантических ловушек (вроде ul > lib-item > li)

2. Если создаёте что-то кастомное (например, <input type="radio" />), по возможности лучше использовать настоящий HTML-элемент (button, input, label) внутри компонентов. Это упростит взаимодействие с клавиатурой и экранными дикторами

3. Не забывайте использовать ARIA-атрибуты, если вы изменяете поведение нативных элементов

4. Придерживайтесь семантической вёрстки (например, страница не должна состоять только из одних div со стилями)

5. Тестируйте доступность – через DevTools или пакет A11Y из состава @angular/cdk

Сборка и публикация

Чтобы опубликовать библиотеку как NPM-пакет вне зависимости от того, куда будет залит конечный артефакт, нужно сделать всего несколько шагов:

1. Создать файл .npmrc с настройками публикации

2. Собрать библиотеку

3. Выполнить команду npm publish

Пример .npmrc выглядит следующим образом:

//npm-registry.corp.com/:token=abc123xyz
@my:registry=https://npm-registry.corp.com/

Обратите внимание на завершающий / – без него NPM не сможет правильно понять путь.

Вам в .npmrc требуется определить адрес сервера, куда будет производиться публикация, а также фактор аутентификации (например, токен, или basic-авторизация).

В итоге нам остаётся только выполнить следующее:

$ npm ci                        # Устанавливаем зависимости строго по package-lock.json. Файл должен находиться в репозиториии
$ npm run build                 # Собираем библиотеку
$ npm publish ./dist/my/ui-kit/ # Публикуем

Этот скрипт можно запускать как вручную, так и на сборочном агенте на этапе CI/CD.

---

Заключение

Мы прошли путь от мотивации до финальной сборки, охватив не только простое создание компонента и стилизацию, но и доступность, тестирование, сборку, публикацию. Всё это не так сложно, как кажется на первый взгляд. Главное – начать, а дальше всё пойдёт куда легче.

Надеюсь, этот материал будет полезен вам в работе.

Happy coding! 🎉