@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/laws/frontend-application.md

@@ -1,6 +1,6 @@
-# Фронтовое приложение
+# Закон о фронтовом приложении
 
-Как устроено то, что рисует экран. Закон держит и сайт, и админку сразу: экран, устроенный
+Как устроено то, что рисует экран. Закон общий для всех приложений сразу: экран, устроенный
 иначе соседнего, пользователь читает заново, а разработчик правит вслепую.
 
 ## Статьи
@@ -18,6 +18,6 @@
   рабочим и молча ничего не делает.
 - **Набор записей приходит с сервера страницей, а не целиком.** Список, растущий вместе с
   данными, однажды перестаёт открываться, и заметно это становится уже у пользователя.
-- **К окружению браузера обращаются только там, где известно, что оно есть.** Прямое
-  обращение к глобальному объекту компилируется и молчит, а падает там, где браузера нет, —
-  на отдаче страницы сервером или в прогоне тестов.
+- **Окружение, которого нет на сервере, приходит экрану извне, а не берётся у среды.**
+  Взятое напрямую, оно компилируется и падает при отдаче страницы сервером — то есть у гостя,
+  а не у того, кто это написал. Места, где иначе нельзя, названы поимённо.

package/assets/laws/lib-imports.md

@@ -1,4 +1,4 @@
-# Импорты между либами
+# Закон об импортах между либами
 
 Кто кого видит. Приложение нарезано на либы, и у каждой объявлен список тех, от кого ей
 разрешено зависеть: так домен, которому незачем знать про чужой транспорт или чужие экраны,
@@ -16,3 +16,16 @@
   дописывается строкой с объяснением, зачем оно понадобилось.
 - **У либы, общей всем трём приложениям, список зависимостей пуст.** Её видит и бэкенд, и
   любая её зависимость стала бы общей для всех сразу.
+- **Место общего символа выбирается по тому, кому он нужен, а не по тому, о чём он.**
+  Разложенные по предмету, символы одного предмета всё равно разъезжаются: часть из них
+  тянет за собой то, что доступно не каждому потребителю.
+- **Своя либа заводится тогда, когда ни одна существующая потребителям не видна.** Заведённая
+  раньше, она стоит пустая: у механики, у которой нет ни экранов, ни состояния, ни запросов,
+  заполнять слои нечем.
+- **У домена заполнен не один слой, а если один — это решено и объяснено.** Домен с
+  единственным заполненным слоем неотличим от заготовки под будущую работу, и заготовка,
+  простоявшая полгода, читается как домен.
+- **Повтор, у которого не совпало имя, находит читатель правки, а не проверка.** Копию с тем
+  же именем или тем же набором значений видно сверкой, а ту же логику, написанную заново под
+  другим именем, — нет. Признак, который ловил бы её, отбивал бы заодно и законное: две
+  одинаковые по форме проверки из разных доменов копией не считаются.

package/assets/laws/lists.md

@@ -0,0 +1,33 @@
+# Закон о списке записей
+
+Как пользователь видит список записей и что делает с ними, не открывая ни одну. Правила общие
+для всех списков: список, устроенный иначе остальных, пользователь читает заново.
+
+Открытая запись, попадание в список и объём данных на строку — предмет других законов.
+
+## Статьи
+
+- **Каждая запись показана отдельной строкой, а каждое её свойство — своим столбцом.**
+- **Нажатие на строку открывает запись.** Действия над записью вынесены отдельно: иначе, чтобы
+  открыть запись, пришлось бы сначала выбирать действие.
+- **Пока список читается, на месте строк видно, что идёт чтение.** Пустую область не отличить
+  от списка, в котором ничего нет.
+- **Пустой список объясняет, почему он пуст.**
+- **На узком экране строка перестраивается так, чтобы её свойства читались без прокрутки
+  вбок.**
+- **Состав и порядок столбцов выбирает пользователь, и выбор сохраняется, когда он уходит с
+  экрана и возвращается.**
+- **Отбор и сортировка стоят отдельно от действий над списком.** Вперемешку они читаются как
+  один набор кнопок, и непонятно, что меняет показанное, а что — сами записи.
+- **Действие, которое с этой записью сейчас сделать нельзя, в её меню не показано.** Что можно
+  с записью, зависит от её состояния и меняется от строки к строке: перечислять в каждой
+  недоступное — показывать пользователю список запретов вместо списка действий.
+- **У записи, с которой нельзя сделать ничего, меню нет вовсе.**
+- **Действие, которое нельзя отменить, спрашивает подтверждение и называет последствие.**
+- **Если список не прочитался, пользователю сказано почему, и повторить попытку можно одним
+  действием.**
+- **Пользователь видит ту сортировку и тот отбор, которые на самом деле применены.**
+  Сортировка по умолчанию видна сразу, а условие, которое сервер не принял, не остаётся на
+  экране как действующее.
+- **Подписи списка берутся из словаря, а не написаны в разметке.** Заголовки столбцов, тексты
+  состояний и названия действий меняются вместе с языком.

package/assets/laws/navigation.md

@@ -0,0 +1,40 @@
+# Закон о навигации по разделам
+
+Как пользователь находит раздел и попадает в него. Правила общие для всех разделов сразу:
+раздел, который ведёт себя иначе остальных, выглядит сломанным.
+
+## Статьи
+
+- **Пункт меню ведёт на отдельный экран со своим адресом,** а не на вкладку внутри чужого
+  экрана и не на что-то всплывающее поверх него. Такой адрес открывается по прямой ссылке,
+  работает после перезагрузки и его можно передать другому человеку.
+- **Раздел, ни один пункт которого пользователю не виден, в меню не показан.**
+- **Адрес открывается только тому, кто видит ведущий на него пункт.**
+- **Видимость пункта и доступ к его адресу считаются по одному и тому же объявлению.** Два
+  объявления рядом рано или поздно разойдутся, и получится, что пункта не видно, а страница
+  открывается.
+- **Чтобы раздел был виден, достаточно любого одного из перечисленных у него прав.** Части
+  экрана закрываются отдельно: экран бывает полезен и тому, кто видит одну его половину, и
+  тому, кто видит другую.
+- **Пункт, у которого экрана ещё нет, виден всем.** Права на него не выдаются: право открывает
+  экран, а экрана нет.
+- **Пункт раздела, которого ещё нет, остаётся видимым.** Исчезнувший пункт не отличить от
+  того, которого никогда и не было. Пункт, закрытый правом, — другое дело: раздел существует,
+  и решает право, поэтому такой пункт не показан вовсе.
+- **Подсказка есть только у пункта, который не нажимается, и объясняет почему.** У остальных
+  она дословно повторяет подпись рядом и ничего не добавляет.
+- **На такой пункт можно навести курсор и попасть с клавиатуры.** Иначе его подсказку не
+  прочитать.
+- **Адрес экрана начинается с адреса раздела, в котором стоит его пункт.**
+- **Активный раздел отмечен, даже когда открыт его вложенный экран.**
+- **Подписи разделов берутся из словаря и меняются вместе с языком без перезагрузки.**
+- **Вложенные пункты раскрываются и наведением, и нажатием.** На сенсорном экране наведения
+  нет, и без второго способа такой раздел не открыть.
+- **Вложенные пункты разбиты на группы с названиями.** Полтора десятка пунктов подряд одним
+  списком не читаются.
+- **Раскрытые пункты помещаются на экран целиком.** Иначе дальний край уходит за границу
+  экрана, и о том, что там что-то есть, пользователь не узнает.
+- **По пункту видно, раскроется ли он.** Иначе пользователь наводит наугад.
+- **На узком экране меню убирается, но раскрывается тем же составом и теми же группами.**
+  Деление на группы там нужно не меньше, чем на широком.
+- **Меню, которое не помещается по высоте, прокручивается.**

package/assets/laws/project-documentation.md

@@ -1,4 +1,4 @@
-# Документация проекта
+# Закон о документации проекта
 
 Что должно быть верно про тексты, которые проект о себе пишет. Расхождение документа с
 работающим приложением беззвучно: ни сборка, ни проверки текстов не читают, поэтому
@@ -11,16 +11,35 @@
   для которых не заведено места, вспоминаются уже после выкатки.
 - **Каждое утверждение документа привязано к месту, где оно исполняется.** Утверждение без
   такого места — намерение, и называть его действующим нельзя.
+- **Предстоящая работа перечислена в одном месте — в очереди работ.** Документ второго списка
+  не заводит: два списка об одной работе расходятся молча, и по ним потом не понять, что
+  сделано, а что нет. Документу остаётся то, что задачей не бывает, — договорённость и
+  решение, которое решено не править.
 - **Привязка не ведёт в код, который никто не зовёт.** Объявленный и никем не используемый
   символ ничего не исполняет, а проверка на нём остаётся зелёной.
 - **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
   действующее указание, и следующий читатель заводит снятое заново.
 - **Документ, разошедшийся с приложением, правится тогда же, когда замечено расхождение.**
   Отложенная правка не случается: расхождение перестаёт быть заметным на следующий день.
-- **Документ описывает то, что есть, а не то, чего не будет.** «Не планируется», «не будет» —
-  намерение, а не свойство приложения: сверить его не с чем, и оно проходит любую проверку,
-  пережив того, кто его писал.
-- **Число в тексте пересчитывается тогда же, когда пишется.** Устаревшее число выглядит так же
-  убедительно, как свежее, и стареет молча — часто внутри той же правки, где появилось.
-- **Работа начинается с описания, а не с кода.** Описанное после того, как написано, повторяет
-  сделанное вместо того, чтобы его задавать, и перестаёт быть требованием.
+- **Расхождение чинится в той стороне, которая неправа, и это не всегда документ.**
+  Состояние, описанное как существующее, но недостижимое в приложении, — дефект приложения:
+  строка читается справкой о работающем, на неё ссылаются как на проверенное, и правка
+  документа под код закрепила бы дыру вместо того, чтобы её показать.
+- **Документ не утверждает о будущем, и следит за этим автор.** «Не планируется», «не будет»
+  — это намерение, а не свойство приложения: сверить его не с чем, и оно проходит любую
+  проверку. Машине это не поручить: открытый вопрос пишется теми же словами, что и обещание,
+  и проверка отбивала бы оба.
+- **Документ утверждает о состоявшемся, а не о том, что должно сработать.** Лечение,
+  записанное готовым до того, как его прогнали, дороже отсутствия записи: следующий читатель
+  берёт его за проверенное — и берёт в тот день, когда лечение понадобилось, а времени на
+  разбор нет. Непрогнанное либо не пишется вовсе, либо названо непроверенным тем же
+  предложением.
+- **Число в тексте пересчитывается тем же изменением, которым пишется, и за этим тоже следит
+  автор.** Устаревшее число выглядит так же, как свежее, а машине их не различить: дата,
+  версия и номер — такие же числа, и проверка, которая знает один способ записи, на другом
+  ошибается молча.
+- **Отказ от слова распространяется на всё, что уже прочитано снаружи, а не только на файлы.**
+  Название работы, её описание и запись о правке живут вне дерева: поиск по файлам их не
+  видит, проверки текстов на них не смотрят, и отказ выглядит сделанным ровно до того, как
+  читатель наткнётся на снятое слово в заголовке. Читатель при этом заключает, что от слова
+  не отказывались вовсе.

package/assets/laws/reuse-first.md

@@ -1,26 +1,31 @@
-# Единообразие приложения
+# Закон о единообразии приложения
 
-Одинаковые вещи в сайте и в админке выглядят и ведут себя одинаково: поле ввода отвечает на
-ошибку так же, как соседнее, панель правки закрывается так же, как в другом разделе, отказ
-подаётся так же на любом экране. Держится это тем, что части собраны из общего кита и общих
-основ, а не написаны заново каждая под себя.
+Одинаковые по смыслу вещи выглядят и ведут себя одинаково во всех частях приложения. Так
+получается потому, что части собраны из одного набора готовых элементов, а не написаны каждая
+по-своему.
 
-Закон говорит о том, что верно для владельца и гостя. Как эти основы устроены в коде — не
-его предмет.
+Закон говорит о том, что верно для пользователя. Как готовое устроено в коде — не его предмет.
 
 ## Статьи
 
-- **Готовое из кита и общих основ берётся, а не пишется заново.** Своя копия расходится с
-  оригиналом с первой же правки, и одинаковые с виду места начинают вести себя по-разному.
-- **Свой примитив и своя основа заводятся только с ведома владельца.** Отступление от общего
-  вида — решение о продукте, а не деталь реализации.
-- **Поле ввода ведёт себя одинаково во всех формах.** Значение, недоступность, тронутость и
-  показ ошибки у всех полей одни.
-- **Панель правки записи ведёт себя одинаково во всех разделах.** Открытие адресом, скелетоны
-  на чтении, спиннер на записи, вопрос о несохранённых правках и закрытие после успеха.
-- **Сообщение об успехе и об отказе подаётся одинаково на всех экранах.** Разный вид у
-  одинаковых по смыслу сообщений читается как разные состояния приложения.
-- **Стили компонента живут в его файле стилей.** Заданные в разметке или в декораторе, они
-  видны только на своём экране, и соседний остаётся с прежним видом.
-- **Раскладка экранов, форм, панелей и окон одна на всё приложение.** Отступы страницы,
-  заголовок, полоса действий и зона содержимого у всех разделов одни, и меняются они разом.
+- **Готовое берут, а не пишут заново.** Своя копия расходится с оригиналом с первой же правки,
+  и одинаковые с виду места начинают вести себя по-разному.
+- **Отойти от общего вида может решить только владелец.** Сделать своё вместо готового
+  спрашивают у него до того, как написана первая строка.
+- **Одинаковые по смыслу элементы ведут себя одинаково везде.** Поле ввода отвечает на ошибку
+  так же, как соседнее; форма правки закрывается так же, как в другой части приложения; об
+  удаче и неудаче сообщают одинаково на любом экране. Когда одинаковое по смыслу выглядит
+  по-разному, пользователь думает, что приложение в разных состояниях.
+- **Раскладка страниц, форм и окон задана один раз и действует на всё приложение.** Отступы,
+  заголовок, полоса действий и место под содержимое у всех одинаковы и меняются разом.
+- **Оформление хранится там же, где сама часть приложения.** Заданное прямо в разметке, оно
+  меняет только свой экран, а соседний остаётся с прежним видом.
+- **Отступление от готового останавливается до того, как написан файл.** Замеченное на
+  чтении правки не ловится: своя разметка сама по себе исправна, и расхождение видно только
+  тому, кто помнит, что готовое для этого уже есть.
+- **Накопленное до запрета сосчитано и не растёт.** Запрет, поставленный на новое, о старом
+  не говорит ничего: без числа накопленное выглядит то ли исчезнувшим, то ли неисчислимым, и
+  сокращать нечего.
+- **Повторяющаяся механика держится в одном месте, а каждый случай объявляет только своё.**
+  Оставленная договорённостью, она пишется заново при каждом применении, и применения
+  незаметно расходятся между собой.

package/assets/laws/shared-code.md

@@ -1,4 +1,4 @@
-# Общий код приложений
+# Закон об общем коде приложений
 
 Что сайт, админка и бэкенд понимают одинаково: размер страницы, набор операторов условия,
 направление порядка, длину поля. Записанное дважды расходится по одному значению за раз, и
@@ -13,7 +13,19 @@
   объявлениями, и одно из них успело стать `25` против `20` у остальных.
 - **Набор значений, уже объявленный в общем пакете, заново не объявляется.** Оператор условия
   и направление порядка лежали на бэкенде рукописной копией того же набора.
+- **Одно и то же значение, записанное в двух местах, считается одним понятием, как бы оно ни
+  называлось.** Совпадение имён обманчиво в обе стороны: одно имя носят разные вещи, а одно и
+  то же понятие расходится по именам — и второе прячет копию надёжнее первого.
 - **Значение из конечного набора сверяется с набором, а не приводится к типу.** Приведение
   принимает любую строку, и порядок молча становится нечитаемым.
 - **Номер страницы меньше единицы читается как первая.** Отрицательный номер доходил до
   переключателя страниц как есть.
+- **Значение, у которого есть общее умолчание, доводом не принимается.** Пока его можно
+  передать, каждый случай вправе назвать своё число, — так размер страницы у одного списка и
+  стал отличаться от остальных.
+- **Клиент и сервер описывают одно и то же одними моделями.** Свои понятия про то же самое
+  расходятся молча: у сервера они успели разойтись с клиентом на отрицательном номере
+  страницы.
+- **Промах в значении выборки на клиенте берёт умолчание, а на сервере становится отказом.**
+  Общим чтением это не покрывается: сервер, принявший неизвестное значение молча, отдаёт не
+  то, что просили, и об этом никто не узнаёт.

package/assets/laws/verifiability.md

@@ -1,4 +1,4 @@
-# Проверяемость
+# Закон о проверяемости
 
 Что считается подтверждением того, что работа сделана. Закон нужен потому, что пересказ
 выглядит так же уверенно, как проверенное утверждение, и отличить их потом нечем: код,
@@ -12,9 +12,38 @@
   выглядит так же, как покрытый сценарий, и долг перестаёт быть заметным.
 - **Тест, проверяющий часть обещанного, считается долгом, а не покрытием.** Иначе сводка
   показывает выполненным то, что выполнено наполовину.
+- **Обещание, данное пользователю, закрывается тестом, который идёт его путём.** Тот же
+  расчёт, проверенный мимо экрана, верен — и обещания не закрывает: между верным решением и
+  тем, что человек его видит, лежит всё, чего проверка не касалась.
+- **Тест, выключенный признаком окружения, покрытием не считается.** В обычном прогоне он не
+  исполняется ни разу, а в сводке выглядит так же, как исполненный.
 - **Упоминание в тесте сценария, которого нет, — отказ.** Так ловится переименованный или
   выкинутый сценарий: без этого он пропадает молча.
 - **Работающее приложение проверяется там, где его видит пользователь.** Отладочный режим
   ведёт себя иначе рабочего, и проверка в нём подтверждает не то, что будет у пользователя.
+- **Перед отправкой правка проверяется тем же набором, что и конвейер, и теми же командами.**
+  Набор, собранный по изменённым файлам, пропускает то, до чего правка дошла связями: проверка
+  зелёная, а конвейер красный. Что проверять, считает инструмент от той же базы, а не память
+  автора.
+- **Проверка признака окружения относится только к тому пути запуска, на котором она
+  сделана.** Пути, которыми одно и то же приложение поднимается, задают признаки по-разному,
+  и подтверждённое на одном из них на остальных неверно — а выглядит проверенным целиком.
 - **Разметка проверяется замером, а не взглядом.** На глаз не отличить отступ от поля и
   выравнивание от совпадения, и расхождение находится уже после выкатки.
+- **Успешный ответ команды означает, что она отработала, а не что нужное состояние
+  наступило.** Часть запросов выполняется наполовину, и об отклонённой части в ответе ничего
+  нет: по коду возврата такой вызов не отличить от исполненного. Поэтому результат читают
+  отдельным запросом, и в отчёт идёт то, что прочитали, а не то, что заказывали.
+- **Служба считается поднятой, когда она выполнила задание, а не когда сообщила о
+  готовности.** Сообщение о готовности говорит лишь, что служба себя объявила: та, которой не
+  досталось ни одного задания, выглядит в нём точно так же, как работающая. Проверяются обе
+  стороны связи — что заказчик выбирает именно её и что задание через неё прошло.
+- **Причина отказа, на которой строится решение, подтверждается измерением, а не
+  правдоподобием.** Объяснение, пришедшее первым, объясняет наблюдаемое не хуже верного:
+  свойство среды и собственный промах выглядят в отказе одинаково, и разводит их только замер,
+  поставленный так, чтобы одно из двух не прошло. Решение, выведенное из неподтверждённой
+  причины, лечит не то — и стоит отката всей работы, а не одной правки.
+- **Если инструмент проверки запрещает приём, которым здесь пользуются постоянно, его правило
+  выключают в настройке инструмента, а не обходят в каждом месте.** Обход приходится повторять
+  столько раз, сколько таких мест, и ни в одном из них не написано, зачем он: со стороны это
+  выглядит ошибкой автора, а не решением.

package/assets/laws/work-conduct.md

@@ -0,0 +1,59 @@
+# Закон о ведении работы
+
+Что должно быть верно про то, как работа идёт от просьбы владельца до её закрытия. Работа
+длится дольше одного захода и переживает перерывы: между заходами исполнитель не помнит
+ничего, а владелец помнит и вынужден пересказывать. Пересказ каждый раз выходит короче
+предыдущего, и работа доделывается по обрывку исходной просьбы.
+
+## Статьи
+
+- **Работа не начинается раньше, чем исполнитель понял, о чём его просят.** Пробел в
+  понимании сам не закрывается: он всплывает в готовой правке и стоит переделки там, где
+  стоил бы вопроса.
+- **Пробел закрывается вопросом владельцу, а не догадкой.** Догадка неотличима от знания:
+  она попадает в работу молча и обнаруживается только при приёмке, когда переделывать дороже
+  всего.
+- **Владельцу не задаётся вопрос, ответ на который уже записан.** Записанное читают до
+  разговора, а не вместо ответа: вопрос о том, что уже решено, обесценивает и остальные.
+- **Решение, однажды записанное, действует, пока его не отменили, и читается до того, как
+  принимается заново.** Отменённое решение следа в работе не оставляет — по результату не
+  видно ни того, что его принимали, ни того, что от него отказались. Принятое заново оно
+  расходится с прежним молча и стоит той же работы второй раз.
+- **Понимание записано там, где идёт работа.** Оставленное в переписке живёт у одного
+  участника и до следующего дня; работу продолжает тот, у кого этой переписки нет.
+- **Сказанное владельцем записывается его словами и задним числом не переписывается.**
+  Пересказ незаметно подгоняется под уже сделанное, и сверять результат становится не с чем.
+- **Договорённость о том, как продукт себя ведёт, записана раньше кода, который её
+  исполняет.** Записанная после, она пишется по коду и повторяет его ошибки: разойтись ей
+  уже не с чем, а значит она ничего не проверяет.
+- **Описание приведено к сделанному прежде, чем работа закрыта.** Договорённость пишется до
+  кода и описывает замысел, а к концу работы приложение отличается и от замысла тоже.
+  Расхождение, отложенное на потом, не находится: назавтра оно уже незаметно, а описание
+  продолжают читать как верное.
+- **Состояние незаконченной работы восстанавливается без участия владельца.** Иначе каждый
+  перерыв стоит ему пересказа, а очередь работ показывает начатое и не говорит, что внутри
+  него сделано.
+- **Замысел и ход работы — разные записи.** Замысел — то, с чем сверяют результат при
+  приёмке; правленный по ходу, он перестаёт отличаться от отчёта, и приёмке сверять нечего.
+- **Сделанное отмечается в одном месте.** Две записи об одном разъезжаются молча, и после
+  этого ни по одной не видно, что осталось.
+- **Решение, принятое по ходу работы, записывается вместе с причиной.** Без причины оно
+  читается как случайное и отменяется следующим заходом, а отменённое возвращается третьим.
+- **Граница работы названа до её начала.** Не названная вслух граница не существует: правка
+  расползается на соседнее, и снимать её приходится вручную.
+- **Признак закрытия работы назван до её начала и проверяем.** «Работает» признаком не
+  является: под ним каждый заход понимает своё, и работа закрывается тогда, когда надоела.
+- **Начатая и брошенная работа видна.** Брошенное на середине выглядит так же, как
+  нетронутое, и второй заход начинает его заново.
+- **Записи о законченной работе не лежат среди записей о текущей.** Закрытое, лежащее рядом
+  с действующим, читается как действующее — тем убедительнее, чем оно старше.
+- **Законченная работа убирает за собой до того, как войдёт в общее дерево.** Потом за
+  оставленным уже никто не следит: работа перешла к следующей задаче, а правки, которой это
+  убрали бы заодно, больше нет.
+- **Достаточность понимания судит тот, кто просил.** Машине видно наличие записи, но не то,
+  что в ней закрыты все пробелы: запись из одной строки проходит так же, как разбор на сто.
+  Признак достаточности, выведенный из объёма или числа вопросов, сам становится целью —
+  исполнитель добирает его, не приближаясь к пониманию.
+- **Незаданный вопрос замечает только тот, кто знает, чего хотел.** Вопрос, которого не
+  задали, следа не оставляет: работа выглядит понятой ровно до приёмки, и вывести отсутствие
+  вопроса не из чего.

package/assets/patterns/admin-lists-screen.md

@@ -0,0 +1,131 @@
+---
+name: admin-lists-screen
+kind: pattern
+rule: lists
+description: Паттерн правила lists. Брать при сборке или правке списочного экрана админки — готовый порядок блоков, разметка <префикс>-table, клик по строке, меню строки с vmTableRowActionsRowType, сортируемый заголовок, слоты тулбара, тост отказа.
+---
+
+# Собрать списочный экран
+
+Паттерн правила `lists`. Что при этом должно быть верно — закон
+`docs/constitution/lists.md`.
+
+## Когда брать
+
+- Заводится новый экран со списком записей.
+- Правится существующий: столбцы, меню строки, тулбар, сортировка.
+
+## Порядок блоков
+
+Раскладку даёт общий блок `<префикс>-page` из слоя приложения, а не стили экрана. Экран отвечает за
+порядок:
+
+```html
+<ng-container rtBlock="<префикс>-page">
+    <header rtElem="header">
+        <!-- div rtElem="header-main" c h1 rtElem="title" + p rtElem="hint" -->
+        <<префикс>-toolbar>
+        <!-- vmToolbarLeft / vmToolbarRight -->
+        <div rtElem="scroll">
+            <!-- overflow-x: auto -->
+            <<префикс>-table rtElem="table">
+            <!-- min-width: max-content -->
+            <<префикс>-pagination>
+        </div>
+    </header>
+</ng-container>
+```
+
+Оба правила прокрутки нужны вместе: с одним контейнером столбцы сжимаются вместо сдвига.
+Тулбар и пагинация своих классов не носят — промежуток задаёт сам `<префикс>-page`.
+
+## Таблица
+
+```html
+<<префикс>-table #rowsTable="vmTable" rtElem="table" clickable [ariaLabel]="'bookingsTableAria' | transloco" [emptyMessage]="'bookingsEmpty'
+| transloco" [tableId]="tableId" [dataSource]="rows()" [columnsConfig]="columnsConfig()" [rowHasActions]="hasRowActions"
+[loading]="loading()">
+```
+
+- `tableId` — ключ, под которым хранится выбор столбцов; он же уходит в асайд настроек.
+- `[columnsConfig]`, а не голый список ключей: из него берутся подписи и для панели настроек, и
+  для карточек на узком экране.
+
+## Клик по строке
+
+```html
+<tr
+    *cdkRowDef="let row; columns: rowsTable.displayedColumns()"
+    cdk-row
+    qa-dataid="bookings-row"
+    vmTableRow
+    (activated)="openAside(row)"></tr>
+```
+
+Строки объявляются на `rowsTable.displayedColumns()`: столбец с меню таблица добавляет сама.
+
+## Меню строки
+
+```html
+<ng-template vmTableRowActions let-row [vmTableRowActionsRowType]="rows()"></ng-template>
+```
+
+```typescript
+protected readonly hasRowActions = (row: IBooking.State): boolean => row.canConfirm || row.canReject;
+```
+
+Доступность действия лежит полем строки (`canConfirm`, `canReject`), а не вызовом метода
+компонента. Действие, которого записи нельзя сделать, из меню убирается целиком. Необратимое
+несёт `danger`, `confirmTitle` и `confirmMessage` с последствием — не «Вы уверены?», а что
+именно произойдёт.
+
+## Сортируемый заголовок
+
+```html
+<th *cdkHeaderCellDef cdk-header-cell vmSortHeader="checkIn">{{ 'bookingsCheckIn' | transloco }}</th>
+```
+
+Колонка помечается `sortable: true` в `columnsConfig`. Заголовок переключает сортировку по
+кругу и отдаёт выбранное событием `(sortChange)`; саму выборку делает экран. Подпись остаётся
+внутри кнопки — из неё берётся доступное имя.
+
+Список приходит уже отсортированным, поэтому экран передаёт таблице текущую сортировку —
+`[sort]="sortModel()"`, — и стрелка стоит на нужной колонке сразу, до первого нажатия. Без
+этого список выглядит неотсортированным, хотя он отсортирован.
+
+## Тулбар
+
+Тулбар поделён на две части слотами: `vmToolbarLeft` — то, что меняет выборку,
+`vmToolbarRight` — действия над списком. Своей раскладки внутри тулбара экран не заводит.
+
+Левый слот — фильтры и поиск. Правый — иконки `<префикс>-icon-button variant="primary"` с парой
+`tooltip` + `ariaLabel` одного текста: обновление (`sync`), настройки столбцов (`sliders-v`),
+создание (`plus`). Если список не прочитался, повторяют той же кнопкой обновления.
+
+## Отказ загрузки
+
+```typescript
+this.#notifications.error(this.#transloco.translate(this.#store.errorKey() ?? 'bookingsLoadFailed'));
+```
+
+Ключ читается сразу после запроса, а не подпиской на сигнал стора: стор делят список и панель
+правки, и подписка показала бы один отказ дважды. Строк `<p role="alert">` над таблицей не
+заводить.
+
+## Проверить
+
+```bash
+npx nx build admin
+```
+
+Продовая сборка обязательна: без `[vmTableRowActionsRowType]` тип `let-row` выводится как
+`unknown`, и падает только она — юниты и дев-сервер проходят.
+
+## Частые промахи
+
+- Свой `@if (rows().length === 0)` — экран собран мимо таблицы.
+- Свой список столбцов вместо `displayedColumns()` — пропадает столбец с меню.
+- Доступность действия считается методом компонента — пересчёт на каждой проверке.
+- `[rowHasActions]` не задан — кнопка «…» висит у строки без действий.
+- Заголовок вложен в тулбар вместо своего `<header>`.
+- `qa-dataid` не проставлен на таблицу, строку, ячейки и элементы тулбара.

package/assets/patterns/admin-nav-item.md

@@ -0,0 +1,71 @@
+---
+name: admin-nav-item
+kind: pattern
+rule: navigation
+description: Паттерн правила navigation. Брать при заведении пункта меню админки, раздела с панелью или нового адреса раздела — одна декларация на пункт и маршрут, флаг раздела без экрана, вложение адреса, подсказка у недоступного пункта. Не брать для панели правки записи — это паттерн entity-aside.
+---
+
+# Пункт меню и адрес раздела
+
+Паттерн правила `navigation`. Что при этом должно быть верно — закон
+`docs/constitution/navigation.md`.
+
+## Когда брать
+
+- Заводится пункт меню админки или раздел с панелью.
+- Появляется новый экран, которому нужен адрес.
+- Пункт надо показать, пока экрана под ним нет.
+
+## Одна декларация на пункт и маршрут
+
+Декларация меню — данные: адреса, ключи словаря, права и флаг раздела. Живёт в
+`libs/admin/common/container/util` и служит и источником пунктов, и источником гейтинга
+маршрутов. Второе объявление рядом с маршрутами разошлось бы с первым, и получилось бы «пункта
+не видно, а страница открывается».
+
+Декларация не импортирует ни один `shell`: иначе граф замкнётся и `npm run check:layers`
+встанет.
+
+## Пункт без экрана
+
+Объявляется **без прав и без адреса**: право открывает экран, а экрана нет. Виден он при этом
+всем. Появится экран — снимается флаг и добавляются права, больше в объявлении править нечего.
+
+Подпись видна, нажатие ничего не делает, подсказка объясняет почему. Носитель подсказки —
+обёртка вокруг кнопки, а сам пункт выключается `aria-disabled`, не нативным `disabled`:
+нативно отключённая кнопка не принимает фокус, и с клавиатуры объяснение недостижимо.
+
+К `aria-disabled` обязательно идёт парное правило стилей `[aria-disabled='true']` — браузер
+этот атрибут сам не рисует. Обработчика нажатия у такого пункта нет вовсе.
+
+## Адрес повторяет раздел
+
+Всё, что стоит в разделе, лежит под его сегментом: экран из «Настроек» — под `/settings`.
+Вложение делается в `apps/admin/src/app/app.routes.ts` через `children` у сегмента раздела;
+`shell` домена монтируется внутрь. Своей либы под раздел не нужно.
+
+Подсветка активного раздела считается префиксом адреса, и списка исключений для неё не
+заводится.
+
+## Данные домена приходят в шапку токеном
+
+Счётчики непрочитанного объявляются интерфейсом и `InjectionToken` в
+`libs/admin/common/container/util`, а связывает токен с реализацией композиционный корень
+(`provideAdminEnvironment`). Права на чужую либу получает только корень — одной строкой в его
+конфиге границ.
+
+Признак доходит до кита предикатом по идентификатору пункта, а не своим полем в декларации:
+раздел домена назван идентификатором своего пункта.
+
+## Частые промахи
+
+- Второе объявление прав рядом с маршрутами.
+- Раздел с панелью, которому дали свой адрес: адрес есть только у пунктов, а раздел виден,
+  если виден хотя бы один пункт внутри.
+- Обход одного верхнего ряда при поиске владельца адреса: разделы обходятся вместе с пунктами
+  их панелей, иначе вложенный экран остаётся без гейтинга.
+- Подсказка у доступного пункта: она дословно повторяет подпись рядом и не добавляет ничего.
+- `vmPopoverTrigger` не поставлен явно: директива попапа по умолчанию открывается нажатием, и
+  два соседних элемента одного ряда ведут себя по-разному.
+- Переезд адреса без правки сквозных спек: они ходят по адресам, и прогон станет красным.
+- Иконка, подобранная «похожая»: отсутствующая добавляется в спрайт и в `<префикс>-icon-names.ts`.