UI

Здесь собраны практические примеры и указания по работе с пользовательским интерфейсом — UI.

Определение UI

UI в контексте системы представляет собой набор модулей, берущих на себя обязанности рендера компонентов, наполняющих систему.

• Пакеты в ui не должны содержать бизнес-логики
• Пакеты в ui не должны быть прибиты гвоздями к какому-то конкретному месту на проекте

Почему следование протоколам важно?

UI - довольно большая часть системы.

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

Практические примеры: создание формы

Задача

Написать форму, отправляющую данные на бэкенд

Реализация

Создаем пакет @ui/form, внутри которого отрисовываем форму и добавляем action, где отправляем данные из формы на бэкенд.

Ошибка

Отправка данных на бэкенд в том или ином виде относится к бизнес части. Это вне скоупа ui, соответственно должно быть реализовано снаружи.

Реализация v2

Открываем пакет @ui/form для конфигурации снаружи: даем возможность указать action, который должен исполняться при нажатии на кнопку. Сам action будем хранить во фрагменте.

ВЫВОД

Форму можно переиспользовать и не нарушена зона ответственности UI, @ui/form будет отвечать только за рендер, как и планировалось

Задача: Сделать модальное окно, оповещающее пользователя об ошибке

Реализация: Создаем пакет @ui/modal, внутри которого верстаем наше модальное окно и выводим его во фрагменте.

Ошибка: Мы замкнули пакет @ui/modal на одном месте на проекте. Если в будущем у нас появится задача сделать модальное окно для обратной связи — нам придется лезть в @ui/modal и верстать там новое окно.

Плюс это противоречит пункту 1: наполнение модального окна относится к бизнесу, а не к ui.

Модальному окну должно быть все равно что в нее кладут.

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

Теперь, когда мы имеем представление о том, что такое ui - перейдем к протоколу работы с этим скоупом.

Протокол работы с пакетами в ui

Разберем основные случаи, в которых вам может потребоваться вносить правки в этом скоупе:

Случай 1: создание нового пакета

Сразу перейду к главному: так как пакет новый — значит нигде не используется, а значит и ломаться нечему.

Это так, но тем не менее, процесс создания пакета в ui требует особого внимания к деталям:

1. Всегда руководствуйтесь SOLID. Если понимать эти принципы — про пункты из блока Что такое ui? можно забыть, это можно расценивать как примеры применения этих принципов.

2. Если пока ничего не понятно про SOLID — смотрим первые 2 пункта в блоке Что такое ui?, и следим за тем, чтобы ваш новый пакет им не противоречил.

3. Всегда типизируйте. Описывайте входные параметры у функций/компонентов и поменьше используйте any (а лучше вообще от него отказаться).

Случай 2: обновление существующего пакета

Это уже более опасный случай, так как ваши правки потенциально могут сломать обратную совместимость в куче мест на проекте.

Чтобы удостовериться в том, что ваши правки имеют место быть и что поломка обратной совместимости допустима, сверяйтесь со следующим алгоритмом:

Как понять что обратная совместимость сломана?

Для начала стоит отметить, что поломка обратной совместимости может проявляться по-разному.

Если вы каким-либо образом внесли правки в API пакета — все несоответствия по проекту выявит команда yarn typecheck.

Если ваши правки не изменили API — вам обязательно стоит проверить рендер этого компонента там, где он используется. Возможно после правок компонент стал выглядеть некорректно, а это можно проверить только самостоятельно.

А нужны ли вообще мои правки?

Так как ответить на этот вопрос самостоятельно у вас вряд ли выйдет — уже на этом этапе стоит обратиться к старшему в команде:

1. Объясните свою потребность
2. Укажите на существующий пакет в ui,
3. Объясните, почему текущая реализация пакета не может предоставить вам то, что вам нужно
4. Расскажите, как вы видите себе модифицированный пакет

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

Мои правки ломают обратную совместимость?

• ДА — тогда стоит трижды задуматься о последствиях. Если осознать их в полной мере у вас не выходит или вы все еще по какой-то причине сомневаетесь — обращайтесь к старшему по команде.

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

• НЕТ — еще раз проверьте правки на наличие антипаттернов и можете их вносить.

Удачи!