Web-components

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

Задачи библиотеки компонентов

Библиотека нужна, чтобы не делать двойную работу и использовать общие элементы повторно. Базовые требования к ней:

• Поддержка версионности
• Простое добавление компонентов
• Совмещение кода компонента с визуальными требованиями к нему.

Как мы эти требования реализовали, подробно расскажу дальше. Если коротко, то использовали Verdaccio, Stencil, импорт svg-файлов из Фигмы.

А давайте сделаем не одну, а две библиотеки

Несколько лет назад мы начали писать новый интерфейс для всей линейки продуктов ISPsystem. Переделку начали с биллинга, а когда встал вопрос о старте ещё одного проекта, задумались о переиспользовании написанного кода. Тогда и пришла мысль о библиотеке компонентов.

Один из наших разработчиков был покорен идеей веб-компонентов, в ту пору не так известных, и заразил нас. Идея и правда отличная: веб-компоненты можно использовать в любых веб-приложениях и на любых фреймворках. А Angular мы только начинали использовать и не были уверены (или душу грела мысль о возможности выбора), что новый проект будем делать именно на нем. Поэтому мы решили сделать две библиотеки: одну на веб-компонентах, вторую на Angular. Первую назвали ispui, вторую ngispui.

Задумали, что компоненты из ispui будем использовать где угодно, как на сайте, так и в проектах на разных фреймворках; а ngispui будет состоять из оберток для веб-компонентов, для удобства использования в ангуляр-проектах.

Светлая идея разбилась о реальность. Писать на чистых веб-компонентах не так удобно и быстро, как на Angular, поэтому мы их не разрабатывали. К тому же поддерживать три проекта (основной, плюс две библиотеки) было не очень удобно. Добавили в ispui пару веб-компонентов и несколько CSS-компонентов, и оставили. Сосредоточились на компонентах на ngispui.

Так основная работа стала вестись в библиотеке для Angular. За время существования мы добавили туда более 50 компонентов. И это действительно принесло плоды: новые проекты стартовали меньше, чем за год, тогда как первые мы делали почти два года.

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

Первая версия библиотеки публиковалась в Git. О её устройстве мырассказывалиещегодназад. Схема рабочая, но не идеальная: все версии были прибиты железно, поэтому воспользоваться преимуществами версионности было нельзя. Как следствие, возникали проблемы при сборке Angular, если у пакетов из библиотеки был один и тот же зависимый пакет, но разных версий.

В комментариях под той статьей нам посоветовали локальный npm-регистр пакетов verdaccio. Мы развернули его локально, с авторизацией через GitLab. Жить стало проще: можно пользоваться всеми фишками версионности. И скрипт публикации был переписан.

При публикации в verdaccio мы смотрим на бранч, из которого происходит публикация, если это не master, то в момент публикации к версии добавляем суффикс dev-текущая дата и время (например 1.0.0-dev12.12.2019). В package.json в репозитории версия остается без префикса. Поднимаем версию и пишем changelog руками. А когда бранч с новой версией компонента мёржится в master, в CI запускается публикация стабильной версии. И ничего в этот момент не нужно править в исходниках. Что удобно.

Требования к добавлению компонентов в библиотеку просты, это тесты + демо-страница. Для быстрого добавления компонентов в библиотеку у нас есть скрипт на plop, который генерирует шаблон демо-страницы и добавляет его в демо-приложение. Разработчику остаётся только сделать пример UI-компонента с описанием API.

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

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

Каждому компоненту своя версия

Библиотека сделана как одно приложение с демо, но каждый компонент публикуется отдельно. То есть каждый компонент это отдельный пакет со своими версиями.

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

Помимо плюсов, такой подход несёт и минусы. Получается, что при публикации одного компонента надо:

• собирать всю библиотеку, проходить все тесты;
• если есть зависимые пакеты, добавлять их в демо-приложение;
• прописывать зависимости компонента в package.json.

Зависимости установлены в демо-приложении и не влияют на сборку и публикацию компонента, поэтому о них легко забыть. Но если их не прописать, это сломает сборку продуктового приложения.

Собираем демо-версию компонента для быстрого ревью

При мерж-реквесте новый компонент должен пройти ревью другого разработчика и дизайнера. Если разработчик еще может собрать приложение, то дизайнеру это вообще ни к чему. Чтобы ревьюер мог сразу посмотреть и код, и то, как он выглядит в браузере, в каждом мерж-реквесте должна быть ссылка на демо-версию компонента.

Сборку демо-версии мы тоже автоматизировали: во время мерж-реквеста в CI запускается задача, которая собирает демо-приложение и загружает его в папку на веб-сервере с nginx. Папка создается по названию бранча, это позволяет хранить много демо-версий компонента одновременно. Разработчик получает готовую ссылку и добавляет к описанию мерж-реквеста.

Превращаем библиотеку в дизайн-систему

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

Дизайнеры сделали в Фигме страницы с описанием компонентов. Мы договорились об едином наименовании. И теперь при сборке библиотеки мы просто скачиваем страницы из Фигмы и вставляем их в виде SVG-файлов в демо страницы с компонентами. Решение не идеальное: на SVG-картинке текст не выделишь и поиском по странице не найдёшь, но прочитать можно.

Когда в библиотеке кроме кода появились дизайнерские требования и правила, она стала полноценной дизайн-системой. Теперь ей пользуются и разработчики, и дизайнеры. Выглядит так:

Считаем, как часто используется компонент

С библиотекой компонентов работает четыре команды. Каждая может вносить изменения, а это чревато: можно кому-то что-то сломать нарочно или нет.

Чтобы это обойти, решили прикрутить статистику. Исходили из мысли, что если человек знает, сколько людей помимо него используют компонент из библиотеки, он будет осторожнее. Или не будет если компонент никто не использует.

Когда к нам в очередной раз пришли практиканты, мы попросили их написать сервис сбора статистики по использованию компонентов из библиотеки. Ребята сделали сервис из нескольких частей:

1. первый скрипт забирает информацию о зависимостях из package.json;
2. второй скрипт парсит html на использование UI-компонентов и атрибутов этих компонентов;
3. компонент-виджет отображает собранную статистику.

Обновляем библиотеку на новую версию Angular

Библиотека компонентов на Angular получилось хорошей: много компонентов, рабочая инфраструктура, понятная схема работы. Но есть у нее и больные места. Одно из них обновление на актуальную версию Angular.

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

Кроме этого, сам процесс обновления и публикации 50+ компонентов тяжелый, даже с учетом автоматизации. Он отнимает время, которое можно было потратить на что-то более полезное и интересное.

Возрождаем библиотеку веб-компонентов

Когда с базовой функциональностью новых продуктов закончили, пришло время добавлять возможности, для которых Angular было уже недостаточно. Встала новая задача плагины на фронтенде. Появилась идея делать их на веб-компонентах и встраивать в приложение Angular. Так получится не привязываться к версии Angular и не понадобится пересобирать плагины при обновлении приложения. Идея отличная, только вот для разработки плагинов требуются UI-компоненты.

Так мы вернулись к библиотеке веб-компонентов ispui. Чтобы не писать на чистых веб-компонентах, мы стали искать библиотеки и фреймворки, которые могли упростить нашу задачу. Angular Elements отпал сразу, из-за привязки к версии Angular, и сама реализация пока сыровата для использования в качестве библиотеки. LitElement довольно простой, но на тот момент не был совместим с Typescript, а Typescript мы любим. Наши ребята в свободное время написали свой класс для написания веб-компонентов AbstractElement, но ресурсов на его разработку и поддержку у нас нет, а на сдачу делать не вариант. А вот Stencil нас покорил: поддержка Typescript, TSX, ангуляр-подобный синтаксис с декораторами, готовая экосистема с тестами, генерацией документации и лоадер для использования в Angular и в других фреймворках.

Сейчас активно разрабатываем библиотеку ispui, учитывая предыдущий опыт и пожелания. Что уже сделали:

• Монорепозиторий управляемый lerna. С ним можно независимо запускать сборку, тесты и публикацию отдельных пакетов.
• Для каждого компонента своя демка в виде html-файла. При сборке она добавляется к демо приложению.
• Для stencil-компонентов генерируется документация, которая вставляется в демо-приложение с описанием API компонента, используемых CSS-переменных.
• Для автоматического поднятия версий и генерации чейнджлога используем написание коммитов по конвенции коммитов. Для этого удобно использовать утилиту git-cz

Заключение: как разрабатывать дизайн-систему, когда ресурсы ограничены

Проект в активной разработке, но подвести промежуточные итоги уже можно. Вот, на что стоит обращать внимание, если вам нужна дизайн-система, а ресурсы ограничены.

• Используйте готовые инструменты по управлению инфраструктурой. Например, lerna.
• Используйте автоматический листинг, настроенные tslint/eslint, stylelint, commitlint. Они позволяют валидировать проект автоматически.
• Автоматизируйте рутинные процессы. Например, создание демо-страниц.
• Используйте фреймворки и библиотеки с развитой инфраструктурой с настроенной тестовой средой, и автоматической генерации документации.

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

_{Photo by Brandon Molitwenik on Unsplash}

Сломанный HTML

В HTML есть много полезных возможностей, которые позволяют реализовывать функциональность без использования JavaScript. Одной из таких фич является возможность отправки формы при нажатии на клавишу Enter в любом поле ввода. Вот пример:

<form>  <label>First name: <input type="text"></label>  <label>Last name: <input type="text"></label>  <button>Send!</button></form>

Вводим текст, нажимаем Enter, данные отправляются на сервер, никакого JavaScript. При желании можно избежать перезагрузки страницы, и сделать отправку данных через AJAX, но и в этом случае количество JS будет минимальным.

А теперь попробуем заменить обычную кнопку на веб-компонент:

<form>  <label>First name: <input type="text"></label>  <label>Last name: <input type="text"></label>  <my-button>Send!</my-button></form>

Веб-компонент my-button внутри себя содержит всё ту же кнопку, визуально никаких отличий нет. А вот отправка формы по нажатию Enter сломалась! Вот демо, можете убедиться в этом сами.

В чем причина такого поведения? Это недоработка спецификации веб-компонентов, вот тикет. В библиотеках разработчики обходят эту проблему с помощью вот такого костыля, например. Сам код выглядит не очень страшно, но давайте на секунду задумаемся: мы пишем кастомный Javascript, чтобы починить поведение, которое сломал веб-стандарт. На всякий случай напомню, что спецификации веб-компонентов уже 8 лет и изо всех утюгов трубят, что она уже production-ready.

Но это ещё не всё, что умудрились сломать в веб-компонентах. В HTML есть такая фича, автоматический фокус поля ввода при нажатии на соседний label. Очень удобно, не обязательно целиться в маленький квадрат, можно нажать на текст рядом. Но не в случае веб-компонентов! Вот пример:

<label>First name: <input type="text"></label><label>Last name: <my-input></label>

На демо видно, что обычный тэг input можно выделить нажатием на "First name", а вот нажатие на "Last name" веб-компонент выделить не может. Проблема! На эту тему есть открытый тикет с последним комментарием 2 года назад, так что скорого разрешения тут ждать не стоит. У разработчиков пока есть только один способ объединить label и input в один компонент. А как быть, если дизайн этого не позволяет? Тут два варианта, либо уговаривать дизайнеров придумать что-то совместимое с веб-компонентами, либо отказаться от веб-компонентов в своем проекте (по крайней мере, от ShadowDOM).

CSP

В своё время нашумел "Рассказ о том, как я ворую номера кредиток и пароли у посетителей ваших сайтов". В качестве одной из мер защиты там упоминается CSP возможность указать белый список доменов, на которые разрешено делать запросы с вашей страницы. Одним из побочных эффектов внедрения CSP является невозможность использовать <style></style> тэги, только внешние файлы через <link rel="stylesheet"> (конечно, можно разрешить style-тэги обратно, через директиву 'unsafe-inline', но как видно из её названия, это будет ослабление вашей защиты).

При чем здесь веб-компоненты? Дело в том, что содержимое ShadowDOM полностью изолированно от внешних стилей, загруженных на страницу, поэтому для стилизации внутри ShadowDOM обычно используются style-тэги, что противоречит CSP. Два самых популярных веб-компонент фреймворка имеют с этим проблемы: Stencil (тикет) и LitElement (тикет).

Свет в конце туннеля есть планируется новое Constructable Stylesheets API, которое позволит создавать стили для ShadowDOM в безопасной форме без необходимости в unsafe-inline. А пока разработчикам придется делать выбор либо CSP, либо веб-компоненты.

Lifecycle-хаос

В хорошей архитектуре компоненты должны выполнять роль кирпичиков, из которых собирается большой проект. Например, мы можем получить такую комбинацию (по аналогии с material-web-components):

<my-menu>    <my-menu-item />    <my-menu-item /></my-menu>

В этой ситуации два веб-компонента должны взаимодействовать друг с другом. Обычно это делается в connectedCallback. Веб-компонент подключается в DOM и осматривается вокруг. В случае подобных композитных компонентов может иметь значение, на каком компоненте этот метод вызовется первым. Проведем тест:

class MyMenu extends HTMLElement {    connectedCallback() {        console.log('my menu')    }}class MyMenuItem extends HTMLElement {    connectedCallback() {        console.log('my menu item')    }}// регистрацияcustomElements.define('my-menu', MyMenu)customElements.define('my-menu-item', MyMenuItem)

Запускаем демо, смотрим в консоль и видим:

"my menu""my menu item""my menu item"

Можно предположить что connectedCallback вызывается на родительском элементе, потом на дочерних. Звучит логично, почему нет. А что, если мы сделаем маленькое изменение и откроем второе демо:

"my menu item""my menu item""my menu"

Как это получилось? Почему my-menu теперь опаздывает? В HTML изменений нет, но мы переставили эти две строки местами

// былоcustomElements.define('my-menu', MyMenu)customElements.define('my-menu-item', MyMenuItem)// сталоcustomElements.define('my-menu-item', MyMenuItem)customElements.define('my-menu', MyMenu)

Оказывается, порядок регистрации элементов влияет на порядок вызова connectedCallback. В практическом смысле это означает то, что мы не можем знать порядок вызова методов, и наш код должен быть готов обработать оба варианта. С вариантом "нас вызвали слишком рано" все просто, добавляем window.setTimeout делаем нашу инициализацию попозже. В случае "нас вызвали слишком поздно" ситуация хуже, мы уже не сможем отменить начатые операции. Поэтому на веб-компонентах не получится сделать нормально работающий компонент спойлера

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

Выводы

В веб-компонентах повсюду раскиданы грабли, грамотно присыпанные маркетингом от Гугла. В стандарте еще много неразрешенных вопросов, которые могут оказаться непреодолимым препятствием для ваших проектов. Было бы полезно знать о потенциальных граблях заранее, чтобы принять более взвешенное решение, использовать ли веб-компоненты и фреймворки на их основе, или остаться с простым старым подходом на HTML/JS/CSS. Надеюсь, эта статья была полезной, спасибо за внимание!

Что такое компоненты?

4 столпа компонентов

1. Кастомные элементы

• Определение поведения элемента
• Реагирование на изменения атрибутов
• Расширение существующих элементов

class ExampleElement extends HTMLElement {  static get observedAttributes() {      return [...]  }  attributeChangedCallback(name, oldValue, newValue) {}  connectedCallback() {}}customElements.define('example-element', ExampleElement)

<example-element>Content</example-element>

class CustomInput extends HTMLInputElement {}customElements.define('custom-input', CustomInput, { extends: 'input' })

<input is="custom-input" />

2. Шаблоны HTML

• Создание готовых структур
• Не отображаются на странице до вызова
• Содержат HTML, CSS и JS

<template id="tweet">  <div class="tweet">    <span class="message"></span>      Written by @    <span class="username"></span>  </div></template>

const template = document.getElementById('tweet')const node = document.importNode(template.content, true)document.body.append(node)

3. Теневой DOM

• Позволяет избежать конфликта стилей
• Придумывать названия (классов, например) становится проще
• Инкапсуляция логики реализации

<div id="shadow-root"></div><script>  const host = document.getElementById('shadow-root')  const shadow = host.attachShadow({ mode: 'open' })</script>

ES и HTML модули

• Добавление при необходимости
• Предварительная генерация не требуется
• Все хранится в одном месте

export class ExampleElement external HTMLElement {}import { ExampleElement } from 'ExampleElement.js'

import { ExampleElement } from 'ExampleElement.html'

Создание собственного компонента

1. Создание шаблона

<template id="user-comment-template">  <style>      ...  </style></template>

2. Добавление разметки

<div class="container">  <div class="avatar-container">    <slot name="avatar"></slot>  </div>  <div class="comment">    <slot name="username"></slot>    <slot name="comment"></slot>  </div></div>

Содержимое слота по умолчанию

<slot name="username">  <span class="unknown">No name</span></slot>

3. Создание класса

class UserComment extends HTMLElement {  constructor() {      super()      this.attachShadow({ mode: 'open' })  }}customElements.define('user-comment', UserComment)

4. Применение теневого контента

connectedCallback() {  const template = document.getElementById('user-comment-template')  const node = document.importNode(template.content, true)  this.shadowRoot.append(node)}

5. Использование компонента

<user-comment>  <img alt="" slot="avatar" src="avatar.png" />  <span slot="username">Matt Crouch</span>  <div slot="comment">This is an example of a comment</div></user-comment>

<!DOCTYPE html><html lang="en">  <head>    <meta charset="UTF-8" />    <meta name="viewport" content="width=device-width, initial-scale=1.0" />    <title>Web Components Example</title>    <style>      body {        display: grid;        place-items: center;      }      img {        width: 80px;        border-radius: 4px;      }    </style>  </head>  <body>    <template id="user-comment-template">      <div class="container">        <div class="avatar-container">          <slot name="avatar">            <slot class="unknown"></slot>          </slot>        </div>        <div class="comment">          <slot name="username">No name</slot>          <slot name="comment"></slot>        </div>      </div>      <style>        .container {          width: 320px;          clear: both;          margin-bottom: 1rem;        }        .avatar-container {          float: left;          margin-right: 1rem;        }        .comment {          height: 80px;          display: flex;          flex-direction: column;          justify-content: center;        }        .unknown {          display: block;          width: 80px;          height: 80px;          border-radius: 4px;          background: #ccc;        }      </style>    </template>    <user-comment>      <img alt="" slot="avatar" src="avatar1.jpg" />      <span slot="username">Matt Crouch</span>      <div slot="comment">Fisrt comment</div>    </user-comment>    <user-comment>      <img alt="" slot="avatar" src="avatar2.jpg" />      <!-- no username -->      <div slot="comment">Second comment</div>    </user-comment>    <user-comment>      <!-- no avatar -->      <span slot="username">John Smith</span>      <div slot="comment">Second comment</div>    </user-comment>    <script>      class UserComment extends HTMLElement {        constructor() {          super();          this.attachShadow({ mode: "open" });        }        connectedCallback() {          const template = document.getElementById("user-comment-template");          const node = document.importNode(template.content, true);          this.shadowRoot.append(node);        }      }      customElements.define("user-comment", UserComment);    </script>  </body></html>

Создание кастомизированного встроенного элемента

1. Создание класса

class RelativeTime extends HTMLTimeElement {}

2. Определение элемента

customElements.define('relative-time', RelativeTime, { extends: 'time' })

3. Установка времени

setTime() {  this.innerHTML = timeago().format(this.getAttribute('datetime'))  this.setAttribute('title', this.getAttribute('datetime'))}

4. Обновление соединения

connectedCAllback() {  this.setTime()}

5. Слежение за изменением атрибутов

static get observedAttributes() {  return ['datetime']}attributeChangedCallback() {  this.setTime()}

6. Добавление на страницу

<time is="relative-time" datetime="2020-09-20T12:00:00+0000">  20 сентября 2020 г. 12:00</time>

<!DOCTYPE html><html lang="en">  <head>    <meta charset="UTF-8" />    <meta name="viewport" content="width=device-width, initial-scale=1.0" />    <title>Web Components Another Example</title>    <!-- timeago.js -->    <script      src="http://personeltest.ru/aways/cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.2/timeago.min.js"      integrity="sha512-SVDh1zH5N9ChofSlNAK43lcNS7lWze6DTVx1JCXH1Tmno+0/1jMpdbR8YDgDUfcUrPp1xyE53G42GFrcM0CMVg=="      crossorigin="anonymous"    ></script>    <style>      body {        display: flex;        flex-direction: column;        align-items: center;      }      input,      button {        margin-bottom: 0.5rem;      }      time {        font-size: 2rem;      }    </style>  </head>  <body>    <input type="text" placeholder="2020-10-20" value="2020-08-19" />    <button>Set Time</button>    <time is="relative-time" datetime="2020-09-19">      19 сентября 2020 г.    </time>    <script>      class RelativeTime extends HTMLTimeElement {        setTime() {          this.innerHTML = timeago.format(this.getAttribute("datetime"));          this.setAttribute("title", this.getAttribute("datetime"));        }        connectedCallback() {          this.setTime();        }        static get observedAttributes() {          return ["datetime"];        }        attributeChangedCallback() {          this.setTime();        }      }      customElements.define("relative-time", RelativeTime, { extends: "time" });      const button = document.querySelector("button");      const input = document.querySelector("input");      const time = document.querySelector("time");      button.onclick = () => {        const { value } = input;        time.setAttribute("datetime", value);      };    </script>  </body></html>