@rt-tools/ui-kit-v2 0.1.0 → 0.3.0

package/src/lib/components/message/CONTEXT.md

@@ -0,0 +1,35 @@
+# `rt-message`
+
+Цветное сообщение внутри страницы: палитра, иконка, необязательное закрытие.
+
+```html
+<rt-message severity="danger" [closable]="true" (closed)="dismiss()">Не удалось сохранить</rt-message>
+```
+
+| вход       | тип                                                                        | умолчание           |
+| ---------- | -------------------------------------------------------------------------- | ------------------- |
+| `severity` | `'info' \| 'success' \| 'warning' \| 'danger' \| 'secondary' \| 'neutral'` | `'info'`            |
+| `icon`     | `IRtIcon.Name \| null`                                                     | `null` → по палитре |
+| `hideIcon` | `boolean`                                                                  | `false`             |
+| `closable` | `boolean`                                                                  | `false`             |
+
+Выход: `closed`. Текст приходит проекцией.
+
+## Главное, что нужно знать
+
+**Это `role="alert"`** — скринридер читает сообщение сразу, перебивая. Тихая заметка, которая не
+перебивает, — это [`rt-note`](../note/CONTEXT.md). Выбор между ними — выбор громкости.
+
+**Крестик просит закрыть, но сам сообщение не убирает**: оно может быть частью формы, и решение
+за потребителем.
+
+## Края
+
+- Иконка подставляется по палитре (`info` → `ico-info`, `success` → `check`,
+  `warning` → `ico-warning`, `danger` → `ico-error`). У `secondary` и `neutral` иконки нет —
+  они не сообщают об исходе.
+- Заданная иконка перебивает умолчание; `hideIcon` гасит любую.
+
+## Рядом
+
+- [`rt-toaster`](../toast/CONTEXT.md) — всплывающее уведомление вместо встроенного.

package/src/lib/components/message/rt-message.component.scss

@@ -1,6 +1,9 @@
-/* rt-message — alert/banner в common/ui (Emulated encapsulation; :host обязательно). */
+/* rt-message — alert/banner в common/ui. ViewEncapsulation.None.
+   Хост адресуется по имени элемента, а не по классу блока: класс `.rt-message` висит
+   и на `<rt-message>`, и на корне шаблона, поэтому правила блока вложены в хост —
+   так они достаются только корню шаблона. */
 
-:host {
+rt-message {
     display: block;
 
     .rt-message {

package/src/lib/components/message-composer/CONTEXT.md

@@ -0,0 +1,46 @@
+# `rt-message-composer`
+
+Поле отправки сообщения: текст, вложения, необязательное форматирование.
+
+```html
+<rt-message-composer
+    placeholder="Ваш вопрос"
+    [attachments]="true"
+    [sending]="sending()"
+    [droppedFiles]="dropped()"
+    (submitted)="send($event)" />
+```
+
+| вход                   | тип                    | умолчание                      |
+| ---------------------- | ---------------------- | ------------------------------ |
+| `placeholder`          | `string`               | `''` → `rtKit.chatPlaceholder` |
+| `attachments`          | `boolean`              | `false`                        |
+| `accept`               | `string`               | `''`                           |
+| `sending` / `disabled` | `boolean`              | `false`                        |
+| `formatting`           | `boolean`              | `false`                        |
+| `toolbar`              | `IRtRichEditorToolbar` | `'full'`                       |
+| `minRows` / `maxRows`  | `number`               | 1 / 6                          |
+| `droppedFiles`         | `File[] \| null`       | `null`                         |
+
+Выход: `submitted` — `{ text, delta?, files }`.
+
+## Главное, что нужно знать
+
+**Отправка разблокируется только при непустом содержимом.** Пробелы значением не считаются; один
+вложенный файл разблокирует отправку и без текста. Во время `sending` поле и кнопка заблокированы —
+иначе второе сообщение ушло бы поверх ещё не доставленного.
+
+**Enter отправляет, Shift+Enter переносит строку.** Набор во время IME-композиции игнорируется.
+
+**`droppedFiles` — вход, а не выход.** Файлы, брошенные в область
+[`rt-file-drop`](../file-drop/CONTEXT.md) снаружи, передаются сюда входом и добавляются к
+вложениям; без `attachments` они игнорируются.
+
+## Края
+
+- После отправки форма сбрасывается целиком — и текст, и файлы.
+- В режиме `formatting` текст уезжает пустым, а содержимое едет в `delta` строкой JSON.
+
+## Рядом
+
+- [`rt-chat`](../chat/CONTEXT.md) — использует это поле как своё.

package/src/lib/components/money-list/CONTEXT.md

@@ -0,0 +1,32 @@
+# `rt-money-list` + `rt-money-row`
+
+Перечень сумм с выделенной итоговой строкой.
+
+```html
+<rt-money-list>
+    <rt-money-row label="Тариф">12 000 ₽</rt-money-row>
+    <rt-money-row label="Скидка" [loading]="!discount()">−1 200 ₽</rt-money-row>
+    <rt-money-row label="Итого" [total]="true">10 800 ₽</rt-money-row>
+</rt-money-list>
+```
+
+`rt-money-list` — чистая раскладка, входов нет.
+
+| вход `rt-money-row` | тип       | умолчание |
+| ------------------- | --------- | --------- |
+| `label`             | `string`  | `''`      |
+| `total`             | `boolean` | `false`   |
+| `loading`           | `boolean` | `false`   |
+
+Сумма приходит проекцией — форматирует её потребитель.
+
+## Главное, что нужно знать
+
+**Считать компонент не умеет.** Итог — это просто строка с `total`, выделенная начертанием;
+складывает суммы вызывающий код.
+
+Во время загрузки сумма подменяется заглушкой, подпись остаётся на месте.
+
+## Рядом
+
+- [`rt-detail-list`](../detail-list/CONTEXT.md) — то же для нечисловых значений.

package/src/lib/components/multiselect/CONTEXT.md

@@ -0,0 +1,43 @@
+# `rt-multiselect<TValue>`
+
+```html
+<rt-field label="Города">
+    <rt-multiselect [formControl]="cities" [options]="options" [maxChips]="3" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход          | тип                                                                          | умолчание                     |
+| ------------- | ---------------------------------------------------------------------------- | ----------------------------- |
+| `options`     | `ReadonlyArray<{ label, value, disabled? }>` (тот же тип, что у `rt-select`) | `[]`                          |
+| `placeholder` | `string`                                                                     | `''` → `rtKit.uiSelectValues` |
+| `maxChips`    | `number`                                                                     | `3`                           |
+
+Значение — `ReadonlyArray<TValue>`. Отдельного выхода выбора нет: значение едет только формой.
+
+## Главное, что нужно знать
+
+**Список не закрывается после выбора.** Иначе каждый следующий вариант приходилось бы выбирать,
+открывая панель заново. Закрывают его Escape, клик мимо или повторный клик по триггеру.
+
+**Выбранное рисуется фишками внутри триггера**, а сверх лимита появляется счётчик `+N`.
+Крестик на фишке снимает выбор и **не раскрывает список** — хотя фишка и лежит внутри кнопки.
+
+## Края
+
+- Значение всегда заменяется новым массивом, прежний не правится: форма видит новую ссылку.
+- `null` в форме читается как пустой выбор.
+- Закрытие панели помечает контрол тронутым; `FormControl.disable()` закрывает раскрытую панель.
+- Подпись фишки берётся из `options` пайпом `rtMultiselectLabel`; для значения вне набора
+  подставляется его строковое представление.
+- Отключённые опции не выбираются, пустой набор даёт `rtKit.uiNoOptions`.
+
+## Клавиатура
+
+Как у [`rt-select`](../select/CONTEXT.md), с одним отличием: `Enter`/`Space` **переключают**
+подсвеченную опцию, оставляя список открытым.
+
+## Рядом
+
+- [`rt-select`](../select/CONTEXT.md) — одно значение.

package/src/lib/components/night-grid/CONTEXT.md

@@ -0,0 +1,31 @@
+# `rt-night-grid`
+
+Плотная сетка ночей: одна клетка — одна ночь, цвет — её состояние.
+
+```html
+<rt-night-grid ariaLabel="Ночи марта" [cells]="cells()" (cellClick)="toggle($event)" />
+```
+
+| вход        | тип                                   | умолчание                      |
+| ----------- | ------------------------------------- | ------------------------------ |
+| `cells`     | `ReadonlyArray<{ id, state, title }>` | **обязателен**                 |
+| `ariaLabel` | `string`                              | `''` → `rtKit.uiNightGridAria` |
+
+Выход: `cellClick` — отдаёт **целую клетку**, а не идентификатор.
+
+`state` — `'free' | 'primary' | 'secondary'`.
+
+## Главное, что нужно знать
+
+**Клетка пустая — весь смысл несёт её подпись.** Внутри нет ни текста, ни иконки: сетка плотная,
+и `title` существует только для всплывающей подсказки и скринридера. Значит подпись обязана быть
+самодостаточной («3 марта — занято»), а не «занято».
+
+## Края
+
+- Клетка — настоящая `<button>`, до неё доходят клавиатурой.
+- Состояние и идентификатор продублированы атрибутами `data-state` и `data-id`.
+- Сетка объявлена `role="group"`, а клетки роли не несут вовсе — они `<button>`, и родной роли
+  им достаточно. Списком сетка была бы неправдой: явная роль на кнопке вытесняет родную, и с
+  `role="listitem"` скринридер называл бы элемент списка, умалчивая, что по нему нажимают.
+  Обернуть каждую кнопку в `listitem` тоже нельзя — клетки прямые дети grid-контейнера.

package/src/lib/components/night-grid/rt-night-grid.component.scss

@@ -1,9 +1,12 @@
-/* rt-night-grid — плотная сетка суток в common/ui (Emulated encapsulation; :host обязательно).
+/* rt-night-grid — плотная сетка суток в common/ui. ViewEncapsulation.None.
+   Хост адресуется по имени элемента, а не по классу блока: класс `.rt-night-grid` висит
+   и на `<rt-night-grid>`, и на корне шаблона, поэтому правила блока вложены в хост —
+   так они достаются только корню шаблона.
 
    Ячейки мелкие и без подписей: сетка читается как индикатор занятости целиком, а
    не как календарь — конкретный день подсказывает нативный title. */
 
-:host {
+rt-night-grid {
     display: block;
 
     .rt-night-grid {

package/src/lib/components/note/CONTEXT.md

@@ -0,0 +1,27 @@
+# `rt-note`
+
+```html
+<rt-note>
+    Тариф меняется
+    <strong>со следующего месяца</strong>
+    .
+</rt-note>
+```
+
+Входов и выходов нет — всё содержимое приходит проекцией.
+
+## Главное, что нужно знать
+
+**Это не уведомление.** `role="note"` — вспомогательный контент: скринридер не перебивает им
+чтение. Громкое цветное сообщение с палитрой, иконкой и закрытием — это
+[`rt-message`](../message/CONTEXT.md). Выбор между ними — выбор громкости, а не оформления.
+
+## Как этим пользоваться
+
+- Блок объявлен на `ng-container`, поэтому вокруг проекции не появляется лишней обёртки:
+  разметка потребителя остаётся прямым потомком host-а, и раскладка на нём (flex/grid) работает.
+- Внутри допустимы строчные теги и управляющие конструкции шаблона.
+
+## Рядом
+
+- [`rt-message`](../message/CONTEXT.md) — то же место на экране, но с severity и закрытием.

package/src/lib/components/notifications-bell/CONTEXT.md

@@ -0,0 +1,29 @@
+# `rt-notifications-bell`
+
+Колокольчик уведомлений с меткой непрочитанного.
+
+```html
+<rt-notifications-bell ariaLabel="Уведомления" unreadLabel="Есть непрочитанные" [unread]="hasUnread()" (clicked)="openPanel()" />
+```
+
+| вход          | тип       | умолчание |
+| ------------- | --------- | --------- |
+| `unread`      | `boolean` | `false`   |
+| `ariaLabel`   | `string`  | `''`      |
+| `unreadLabel` | `string`  | `''`      |
+
+Выход: `clicked`.
+
+## Главное, что нужно знать
+
+**Компонент ничего не открывает** — он только сообщает о нажатии. Панель уведомлений рисует
+приложение.
+
+**У метки своя подпись.** Точка несёт смысл, а не оформление: она объявлена `role="img"` с
+`aria-label`, иначе скринридер сказал бы только «Уведомления», не упомянув непрочитанное.
+
+Обе подписи задаёт приложение — своих слов у кита здесь нет.
+
+## Рядом
+
+- [`rt-header`](../header/CONTEXT.md) — слот `[rtHeaderBell]`, куда его обычно кладут.

package/src/lib/components/page-header/CONTEXT.md

@@ -0,0 +1,33 @@
+# `rt-page-header`
+
+Полоса разделов приложения: плоские пункты-ссылки и пункты с раскрывающейся панелью.
+
+```html
+<rt-page-header ariaLabel="Разделы" [items]="sections()" [user]="user()" (itemClick)="go($event)" (userClick)="openProfile()" />
+```
+
+| вход        | тип                         | умолчание                |
+| ----------- | --------------------------- | ------------------------ |
+| `items`     | `ReadonlyArray<Item>`       | `[]`                     |
+| `user`      | `{ name, avatar? } \| null` | `null`                   |
+| `userTitle` | `string`                    | `''`                     |
+| `userMenu`  | `TemplateRef \| null`       | `null`                   |
+| `ariaLabel` | `string`                    | `''` → `rtKit.uiMainNav` |
+
+Выходы: `itemClick`, `userClick`.
+
+## Главное, что нужно знать
+
+**Пункт с `route` — это ссылка, пункт с `columns` — кнопка.** Второму некуда вести: он
+раскрывает панель, а переходят уже её пункты. Подсветку активного даёт `routerLinkActive`, то
+есть маршрутизатор, а не входы компонента.
+
+**Узкая разметка отдельная**, а не свёрнутая стилями: те же разделы доступны через кнопку-бургер
+(`header-nav-burger`), и оба варианта живут в DOM одновременно.
+
+## Края
+
+- `unread: true` у пункта рисует отдельную точку.
+- Панель вложенных разделов раскрывается по наведению и живёт в оверлее CDK — до наведения её в
+  документе нет.
+- Раскладку панели (колонки и группы) готовит потребитель: компонент их не считает.

package/src/lib/components/pagination/CONTEXT.md

@@ -0,0 +1,43 @@
+# `rt-pagination`
+
+```html
+<rt-pagination
+    [pageModel]="page()"
+    [perPageOptions]="[20, 50, 100]"
+    [loading]="loading()"
+    (pageChange)="load($event, page().pageSize)"
+    (perPageChange)="load(1, $event)" />
+```
+
+| вход             | тип                                                   | умолчание       |
+| ---------------- | ----------------------------------------------------- | --------------- |
+| `pageModel`      | `IPageModel` (`pageNumber`, `pageSize`, `totalCount`) | **обязателен**  |
+| `perPageOptions` | `ReadonlyArray<number>`                               | `[20, 50, 100]` |
+| `loading`        | `boolean`                                             | `false`         |
+
+| выход           | тип      |
+| --------------- | -------- |
+| `pageChange`    | `number` |
+| `perPageChange` | `number` |
+
+## Главное, что нужно знать
+
+**Компонент не листает — он просит.** Страницу меняет потребитель, передав новый `pageModel`.
+Поэтому клик по уже открытой странице, выход за границы диапазона и выбор того же размера
+страницы событий **не поднимают**: лишний запрос был бы за них.
+
+**Полоса прячет себя целиком**, когда записей меньше самого мелкого варианта размера страницы
+(`display: none` на host-е): листать нечего, а строка под таблицей всё равно занимала бы место.
+
+## Края
+
+- Во время загрузки заблокированы и номера, и стрелки — иначе второй клик ушёл бы поверх ещё
+  не пришедшего ответа.
+- Полоса номеров показывает первую, последнюю и по одному соседу открытой страницы; между ними —
+  «…». При единственной странице номеров нет вовсе.
+- Узкая и широкая разметки живут в DOM **одновременно** (`pagination-compact` и
+  `pagination-nav`): какую показать, решает медиазапрос, а не условная отрисовка.
+- **У пустого набора нет своего вида строки диапазона — бар при нём спрятан целиком.** Ветка на
+  `rtKit.uiRangeEmpty` тут была, но показать её не могло ничто: правило видимости прячет бар
+  раньше. Сам ключ в словаре остался (он часть публичного `rtKit`), но кит его больше не читает.
+  Про пустоту говорит [`rt-empty-state`](../empty-state/CONTEXT.md), а не пагинация.

package/src/lib/components/photo-viewer/CONTEXT.md

@@ -0,0 +1,30 @@
+# `rt-photo-viewer`
+
+Полноэкранный просмотр кадров. Открывается через [`RtDialogService`](../dialog/CONTEXT.md).
+
+```typescript
+const ref: RtDialogRef<number> = this.#dialog.open<RtPhotoViewerComponent, IRtPhotoViewer.Data, number>(RtPhotoViewerComponent, {
+    data: { photos, startIndex: 2, panel: this.panelTpl },
+});
+ref.afterClosed().subscribe((lastIndex?: number): void => scrollListTo(lastIndex));
+```
+
+Данные приходят токеном `RT_DIALOG_DATA`: `photos`, `startIndex`, необязательный `panel`
+(шаблон подвала, получает текущий кадр и его номер).
+
+## Главное, что нужно знать
+
+**При закрытии отдаётся номер кадра, на котором закрыли.** Список за просмотрщиком
+прокручивается к тому же кадру — иначе пользователь терял бы место.
+
+**Лента замкнута**: с последнего кадра вперёд — на первый, с первого назад — на последний.
+
+**Рисуются только текущий и соседние кадры.** Длинная лента разом не грузится; остальные
+`<figure>` остаются пустыми до подхода.
+
+## Края
+
+- Фокус ставит сам компонент (`role="dialog"`, `tabindex="-1"`), а `cdkTrapFocus` держит Tab
+  внутри без авто-захвата — иначе клавиши переставали бы листать.
+- Стрелки-кнопки не рисуются, если кадр один.
+- Управление кадром (удалить, сделать обложкой) приходит снаружи шаблоном `panel`.

package/src/lib/components/photo-viewer/rt-photo-viewer.component.scss

@@ -1,112 +1,113 @@
-:host {
+/* rt-photo-viewer — ViewEncapsulation.None: правила таргетируют BEM-класс блока.
+   `.rt-photo-viewer` — сам хост (шаблон начинается с ng-container, класс ставит host). */
+
+.rt-photo-viewer {
     display: block;
     width: 100vw;
     height: 100vh;
     height: 100dvh;
     background: var(--rt-color-bg-inverse);
 
-    .rt-photo-viewer {
-        // Обёртка существует ради ловушки фокуса и повторяет размеры хоста:
-        // display: contents ломает ловушку — ей нужен настоящий бокс
-        &__surface {
-            position: absolute;
-            inset: 0;
-        }
+    // Обёртка существует ради ловушки фокуса и повторяет размеры хоста:
+    // display: contents ломает ловушку — ей нужен настоящий бокс
+    &__surface {
+        position: absolute;
+        inset: 0;
+    }
 
-        &__bar {
-            position: absolute;
-            z-index: 1;
-            top: 0;
-            right: 0;
-            left: 0;
-            display: flex;
-            align-items: center;
-            justify-content: space-between;
-            padding: var(--rt-space-4) var(--rt-space-5);
-            color: var(--rt-color-text-inverse);
-            gap: var(--rt-space-4);
-        }
+    &__bar {
+        position: absolute;
+        z-index: 1;
+        top: 0;
+        right: 0;
+        left: 0;
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: var(--rt-space-4) var(--rt-space-5);
+        color: var(--rt-color-text-inverse);
+        gap: var(--rt-space-4);
+    }
 
-        &__counter {
-            font-size: var(--rt-text-sm);
-            font-variant-numeric: tabular-nums;
-        }
+    &__counter {
+        font-size: var(--rt-text-sm);
+        font-variant-numeric: tabular-nums;
+    }
 
-        &__track {
-            display: flex;
-            overflow: auto hidden;
-            width: 100%;
-            height: 100%;
+    &__track {
+        display: flex;
+        overflow: auto hidden;
+        width: 100%;
+        height: 100%;
 
-            // Свайп, инерцию и прилипание кадра даёт браузер
-            scroll-snap-type: x mandatory;
-            scrollbar-width: none;
-        }
+        // Свайп, инерцию и прилипание кадра даёт браузер
+        scroll-snap-type: x mandatory;
+        scrollbar-width: none;
+    }
 
-        &__slide {
+    &__slide {
+        display: flex;
+        flex: 0 0 100%;
+        align-items: center;
+        justify-content: center;
+        padding: var(--rt-space-10) var(--rt-space-4);
+        margin: 0;
+        scroll-snap-align: center;
+
+        picture {
             display: flex;
-            flex: 0 0 100%;
+            width: 100%;
+            height: 100%;
             align-items: center;
             justify-content: center;
-            padding: var(--rt-space-10) var(--rt-space-4);
-            margin: 0;
-            scroll-snap-align: center;
-
-            picture {
-                display: flex;
-                width: 100%;
-                height: 100%;
-                align-items: center;
-                justify-content: center;
-            }
         }
+    }
 
-        // Кадры вертикальные, поэтому ограничение по высоте важнее, чем по ширине
-        &__image {
-            display: block;
-            max-width: 100%;
-            max-height: 100%;
-            object-fit: contain;
-        }
+    // Кадры вертикальные, поэтому ограничение по высоте важнее, чем по ширине
+    &__image {
+        display: block;
+        max-width: 100%;
+        max-height: 100%;
+        object-fit: contain;
+    }
 
-        // Панель правки: светлая полоса поверх тёмного просмотра — она рабочая
-        // область, а не часть кадра
-        &__panel {
-            position: absolute;
-            z-index: 1;
-            right: 0;
-            bottom: 0;
-            left: 0;
-            padding: var(--rt-space-4) var(--rt-space-5);
-            background: var(--rt-color-bg-surface);
-            color: var(--rt-color-text-primary);
-        }
+    // Панель правки: светлая полоса поверх тёмного просмотра — она рабочая
+    // область, а не часть кадра
+    &__panel {
+        position: absolute;
+        z-index: 1;
+        right: 0;
+        bottom: 0;
+        left: 0;
+        padding: var(--rt-space-4) var(--rt-space-5);
+        background: var(--rt-color-bg-surface);
+        color: var(--rt-color-text-primary);
+    }
 
-        /* TODO: отрефакторить это дерьмо */
-        &__bar rt-icon-button,
-        &__arrow-prev,
-        &__arrow-next {
-            --rt-icon-button-color: var(--rt-color-text-inverse);
-            --rt-icon-button-color-bg-hover: color-mix(in srgb, var(--rt-color-text-inverse) 24%, transparent);
+    /* TODO: отрефакторить это дерьмо */
+    &__bar rt-icon-button,
+    &__arrow-prev,
+    &__arrow-next {
+        --rt-icon-button-color: var(--rt-color-text-inverse);
+        --rt-icon-button-color-bg-hover: color-mix(in srgb, var(--rt-color-text-inverse) 24%, transparent);
 
-            border-radius: var(--rt-radius-md);
-            background: color-mix(in srgb, var(--rt-color-bg-inverse) 55%, transparent);
-        }
+        border-radius: var(--rt-radius-md);
+        background: color-mix(in srgb, var(--rt-color-bg-inverse) 55%, transparent);
+    }
 
-        &__arrow-prev,
-        &__arrow-next {
-            position: absolute;
-            top: 50%;
-            transform: translateY(-50%);
-        }
+    &__arrow-prev,
+    &__arrow-next {
+        position: absolute;
+        top: 50%;
+        transform: translateY(-50%);
+    }
 
-        &__arrow-prev {
-            left: var(--rt-space-3);
-        }
+    &__arrow-prev {
+        left: var(--rt-space-3);
+    }
 
-        &__arrow-next {
-            right: var(--rt-space-3);
-        }
+    &__arrow-next {
+        right: var(--rt-space-3);
     }
 
     // С панелью кадру нужно место под неё, иначе низ снимка уходит под полосу
@@ -117,15 +118,13 @@
     }
 
     @media (width <= 700px) {
-        .rt-photo-viewer {
-            &__arrow-prev,
-            &__arrow-next {
-                display: none;
-            }
-
-            &__slide {
-                padding: var(--rt-space-12) 0;
-            }
+        &__arrow-prev,
+        &__arrow-next {
+            display: none;
+        }
+
+        &__slide {
+            padding: var(--rt-space-12) 0;
         }
     }
 }