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

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

@@ -0,0 +1,54 @@
+# `[rtPopover]`
+
+Примитив плавающей панели поверх CDK Overlay. На нём стоят
+[`rt-select`](../select/CONTEXT.md), [`rt-multiselect`](../multiselect/CONTEXT.md),
+[`rt-autocomplete`](../autocomplete/CONTEXT.md) и пояснение в [`rt-field`](../field/CONTEXT.md).
+
+```html
+<button type="button" rtPopoverTrigger="click" rtPopoverWidth="trigger" [rtPopover]="tpl">Открыть</button>
+<ng-template #tpl><div>Содержимое панели</div></ng-template>
+```
+
+| вход (алиас)                            | тип                              | умолчание |
+| --------------------------------------- | -------------------------------- | --------- |
+| `rtPopover`                             | `TemplateRef \| null`            | `null`    |
+| `rtPopoverTrigger`                      | `'click' \| 'hover' \| 'manual'` | `'click'` |
+| `rtPopoverWidth`                        | `'trigger' \| 'auto'`            | `'auto'`  |
+| `rtPopoverAlign`                        | `'start' \| 'end'`               | `'start'` |
+| `rtPopoverFitViewport`                  | `boolean`                        | `false`   |
+| `rtPopoverOffsetY` / `rtPopoverOffsetX` | `number`                         | `4` / `0` |
+| `rtPopoverPanelClass`                   | `string`                         | `''`      |
+| `rtPopoverContext`                      | `unknown`                        | `null`    |
+| `rtPopoverDisabled`                     | `boolean`                        | `false`   |
+
+Выходы: `rtPopoverOpened`, `rtPopoverClosed`. Публичное API: `open()`, `close()`, `toggle()`,
+`isOpen()` — работают **во всех режимах**; `trigger` определяет только автоматические слушатели.
+
+## Главное, что нужно знать
+
+**Панель живёт в оверлее CDK, а не внутри host-элемента.** Поэтому её не режет `overflow: hidden`
+предков (таблицы, асайды, карточки) — но и искать её в разметке компонента бесполезно: в тестах
+она ищется по документу.
+
+**Вложенная панель не считается «кликом снаружи».** Панель, открытая из нашей (список
+`rt-select`, календарь, вложенное меню), лежит в DOM рядом, отдельным оверлеем. Без этой проверки
+меню профиля закрывалось бы, стоило потянуться к списку языков, а выбранное значение не доходило
+бы до обработчика. Вложенность определяется порядком панелей в контейнере оверлеев: открытая позже
+считается вложенной.
+
+## Как этим пользоваться
+
+- `manual` — для контролов со своим жестом (поле с подсказками открывает панель по набору текста).
+- `hover` держит панель открытой при переходе курсора на неё: закрытие отложено на 100 мс, и
+  наведение на панель отсрочку гасит.
+- `fitViewport` **выключен по умолчанию**: панель стоит там, куда её ставит привязка к триггеру,
+  даже если часть ушла за экран. Включать для широких и высоких панелей, иначе их содержимое
+  остаётся недостижимым.
+- `rtPopoverPanelClass` добавляется **к** базовому `rt-popover-panel`, а не вместо него.
+- Escape и клик мимо закрывают панель во всех режимах.
+
+## Рядом
+
+- [`[rtTooltip]`](../tooltip/CONTEXT.md) — та же механика, но для короткой подсказки.
+- [`[rtConfirm]`](../confirm-popover/CONTEXT.md) — панель подтверждения.
+- [`rt-menu`](../menu/CONTEXT.md) — меню действий (на CDK-оверлее напрямую).

package/src/lib/components/rich-editor/CONTEXT.md

@@ -0,0 +1,36 @@
+# `rt-rich-editor`
+
+Поле ввода с форматированием поверх Quill. Значение — модель Quill (`IQuillDelta`), а не HTML.
+
+```html
+<rt-field label="Описание">
+    <rt-rich-editor placeholder="Опишите задачу" toolbar="full" [formControl]="description" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход          | тип                    | умолчание |
+| ------------- | ---------------------- | --------- |
+| `placeholder` | `string`               | `''`      |
+| `toolbar`     | `IRtRichEditorToolbar` | `'full'`  |
+
+Выход: `enterPressed` — Enter без Shift (перенос при этом гасится).
+
+## Главное, что нужно знать
+
+**Quill грузится динамическим импортом** и создаётся только после первой отрисовки — чтобы не
+тянуть его в основную сборку приложения. Отсюда два следствия:
+
+- значение, пришедшее из формы **до** готовности редактора, откладывается и применяется при его
+  создании — оно не теряется;
+- в тестах модуль подменяется (`jest.mock('quill', …)`): сам Quill в jsdom не поднимается.
+
+**Пустой текст пишет в форму `null`, а не пустой набор операций.** Так «пусто» отличимо от
+«есть форматирование без текста» — на этом стоит проверка обязательности поля.
+
+## Рядом
+
+- [`rt-delta-view`](../delta-view/CONTEXT.md) — показ той же модели без редактирования.
+- [`rt-message-composer`](../message-composer/CONTEXT.md) — использует редактор в режиме
+  форматирования.

package/src/lib/components/section-nav/CONTEXT.md

@@ -0,0 +1,27 @@
+# `rt-section-nav`
+
+Плитки разделов: иконка, подпись, подсветка текущего.
+
+```html
+<rt-section-nav [items]="sections()" (itemSelect)="goTo($event)" />
+```
+
+| вход    | тип                                      | умолчание      |
+| ------- | ---------------------------------------- | -------------- |
+| `items` | `readonly { id, icon, label, active }[]` | **обязателен** |
+
+| выход        | тип                              |
+| ------------ | -------------------------------- |
+| `itemSelect` | `string` — идентификатор раздела |
+
+## Главное, что нужно знать
+
+**Активность приходит снаружи, в самом наборе.** Нажатие только просит открыть раздел; подсветку
+двигает уже новый набор, пришедший после перехода. Компонент состояния не держит.
+
+## Края
+
+- Плитка — настоящая `<button>`: до неё доходят клавиатурой.
+- Активная плитка помечена тремя способами: модификатором, `data-active` и `aria-current="page"`.
+- Идентификатор дублируется атрибутом `data-key`.
+- Пустой набор рисует пустую навигацию.

package/src/lib/components/section-nav/rt-section-nav.component.scss

@@ -1,3 +1,6 @@
+/* rt-section-nav — ViewEncapsulation.None: правила таргетируют BEM-класс блока.
+   `.rt-section-nav` — сам хост (шаблон начинается с ng-container, класс ставит host). */
+
 .rt-section-nav {
     display: flex;
     gap: var(--rt-space-md);
@@ -47,6 +50,9 @@
     }
 }
 
-:host-context([data-theme='dark']) .rt-section-nav__tile--active {
+/* Тёмная тема: активная плитка на тёмной поверхности берёт свой фон.
+   Раньше правило было записано через `:host-context`, который под None не
+   совпадает ни с чем, — тема задаётся атрибутом на предке, и им же адресуется. */
+[data-theme='dark'] .rt-section-nav__tile--active {
     background: var(--rt-blue-900);
 }

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

@@ -0,0 +1,54 @@
+# `rt-select<TValue>`
+
+```html
+<rt-field label="Город">
+    <rt-select placeholder="Выберите" [formControl]="city" [options]="cities" [filter]="true" (selectionChange)="onPicked($event)" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход                | тип                                          | умолчание               |
+| ------------------- | -------------------------------------------- | ----------------------- |
+| `options`           | `ReadonlyArray<{ label, value, disabled? }>` | `[]`                    |
+| `placeholder`       | `string`                                     | `''`                    |
+| `iconLeft`          | `IRtIcon.Name \| null`                       | `null`                  |
+| `filter`            | `boolean`                                    | `false`                 |
+| `filterPlaceholder` | `string`                                     | `''` → `rtKit.uiSearch` |
+
+| выход             | тип              |
+| ----------------- | ---------------- |
+| `selectionChange` | `TValue \| null` |
+
+## Главное, что нужно знать
+
+**Подпись выбранного берётся из `options`, а не хранится.** В значении лежит только `value`;
+если набор опций пришёл позже или сменился, подпись перерисуется сама. Значение, которого нет в
+наборе, покажется пустой строкой.
+
+**`selectionChange` — это не дубль формы.** Форма получает значение через
+`ControlValueAccessor`; отдельный выход нужен там, где на выбор надо среагировать (перезагрузить
+зависимый список), не подписываясь на `valueChanges` всей формы. Очистка крестиком тоже
+поднимает его — со значением `null`.
+
+## Клавиатура
+
+- Закрытый список раскрывают `ArrowDown`, `ArrowUp`, `Enter`, `Space` — и сразу подсвечивают
+  первую доступную опцию.
+- Стрелки **перешагивают отключённые опции** и заворачиваются по кругу.
+- `Enter`/`Space` выбирают подсвеченную, `Escape` закрывает без выбора.
+- Опции не фокусируются поодиночке: подсвеченная называется скринридеру через
+  `aria-activedescendant` на триггере.
+
+## Края
+
+- Закрытие списка помечает контрол тронутым и сбрасывает строку фильтра.
+- `FormControl.disable()` **закрывает уже раскрытый** список — иначе панель висела бы над
+  контролом, которым уже нельзя пользоваться.
+- Пустой набор опций рисует строку `rtKit.uiNoOptions`.
+- Ширина панели равна ширине триггера (`rtPopoverWidth="trigger"`).
+
+## Рядом
+
+- [`rt-multiselect`](../multiselect/CONTEXT.md) — тот же список, но с несколькими значениями.
+- [`rt-autocomplete`](../autocomplete/CONTEXT.md) — когда набор ищут на сервере.

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

@@ -0,0 +1,41 @@
+# `rt-skeleton`
+
+```html
+<rt-skeleton shape="rectangle" size="md" width="240px" height="16px" borderRadius="xl" [animation]="true" />
+```
+
+| вход           | тип                                            | умолчание          |
+| -------------- | ---------------------------------------------- | ------------------ |
+| `shape`        | `'rectangle' \| 'circle' \| 'square'`          | `'rectangle'`      |
+| `size`         | `'sm' \| 'md' \| 'lg'`                         | `'md'`             |
+| `width`        | `string` (любая CSS-длина)                     | `'100%'`           |
+| `height`       | `string`                                       | `'10px'`           |
+| `borderRadius` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| null` | `null` (по фигуре) |
+| `animation`    | `boolean`                                      | `true`             |
+
+Шкала размеров: `sm` 10px, `md` 15px, `lg` 20px. Шкала скруглений: `xs` 2, `sm` 4, `md` 6,
+`lg` 10, `xl` 999px.
+
+## Главное, что нужно знать
+
+**Напрямую его почти не ставят.** Условную отрисовку делает
+[`rt-skeleton-wrapper`](../skeleton-wrapper/CONTEXT.md): он решает, что показать — заглушку или
+проекцию, — и пробрасывает сюда все эти входы. Прямой `rt-skeleton` уместен там, где заглушка
+рисуется без пары «загрузка/контент»: сетка карточек-призраков, макет страницы.
+
+## Края
+
+- **Умолчание высоты — 10px, хотя умолчание размера — `md` (15px).** Расхождение намеренное:
+  полоска текста тоньше шага размера. Прямоугольник слушается `height`, круг и квадрат — нет.
+- Круг и квадрат берут сторону из `size` и **игнорируют** `width`/`height`.
+- **`borderRadius: null` значит «по фигуре», а не «без скругления»:** прямоугольник берёт `xl`,
+  квадрат — `sm` (пилюля из квадрата не квадрат). Заданное значение перебивает умолчание у
+  обоих. Умолчанием нельзя держать сам `xl` — тогда явный `xl` неотличим от невыставленного, и
+  квадрату приходится прибивать `sm` жёстко, молча теряя вход.
+- Круг — единственное исключение: он всегда `50%`, потому что круг и есть это скругление.
+- `animation` принимает голый атрибут (`animation` без значения = `true`).
+- Мерцание снимается у пользователей с `prefers-reduced-motion` — правило в SCSS.
+
+## Рядом
+
+- [`rt-skeleton-wrapper`](../skeleton-wrapper/CONTEXT.md) — обёртка «загрузка ↔ контент».

package/src/lib/components/skeleton-wrapper/CONTEXT.md

@@ -0,0 +1,24 @@
+# `rt-skeleton-wrapper`
+
+Обёртка «загрузка ↔ содержимое»: показывает заглушку или проекцию.
+
+```html
+<rt-skeleton-wrapper width="240px" height="16px" [isLoading]="!tour()">{{ tour()?.title }}</rt-skeleton-wrapper>
+```
+
+| вход                                            | тип                                           | умолчание |
+| ----------------------------------------------- | --------------------------------------------- | --------- |
+| `isLoading`                                     | `boolean`                                     | `false`   |
+| `width`                                         | `string`                                      | `'100%'`  |
+| `height`                                        | `string`                                      | `'15px'`  |
+| `shape` / `size` / `borderRadius` / `animation` | как у [`rt-skeleton`](../skeleton/CONTEXT.md) |           |
+
+## Главное, что нужно знать
+
+**Умолчание — «загрузка закончилась».** Обёртку часто ставят на путь, где данные уже есть,
+поэтому `isLoading` по умолчанию `false`.
+
+**Подмена полная**: пока идёт загрузка, проекция не отрисована вовсе — не спрятана, а
+отсутствует. Значит внутрь можно смело класть выражения по ещё не пришедшим данным.
+
+Высота по умолчанию здесь **15px**, а у самого `rt-skeleton` — 10px.

package/src/lib/components/skeleton-wrapper/rt-skeleton-wrapper.component.scss

@@ -1,4 +1,8 @@
-:host {
+/* rt-skeleton-wrapper — ViewEncapsulation.None: правило таргетирует BEM-класс блока.
+   `.rt-skeleton-wrapper` — сам хост: своей разметки блока нет, внутри либо
+   rt-skeleton, либо спроецированное содержимое. */
+
+.rt-skeleton-wrapper {
     display: inline-flex;
     width: 100%;
 }

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

@@ -0,0 +1,39 @@
+# `rt-spinner`
+
+```html
+<rt-spinner color="primary" [diameter]="32" />
+```
+
+| вход       | тип                                      | умолчание   |
+| ---------- | ---------------------------------------- | ----------- |
+| `diameter` | `number \| string` (px)                  | `32`        |
+| `color`    | `'primary' \| 'neutral' \| 'on-primary'` | `'primary'` |
+
+Выходов нет. Собственной разметки нет — кольцо рисуется на host-е.
+
+## Главное, что нужно знать
+
+**Спиннер не решает, показывать ли себя.** Ни условной отрисовки, ни подложки внутри нет: и то,
+и другое — дело вмещающего. Таблица рисует свой sticky-overlay и кладёт спиннер внутрь, кнопка
+подменяет им иконку.
+
+Диаметр едет свойством оформления `--rt-spinner-diameter`, а не классом, — поэтому размер
+задаётся произвольным числом, а не шкалой.
+
+## Как этим пользоваться
+
+- `on-primary` — для спиннера поверх залитой основной палитрой поверхности (кнопка, баннер).
+- `neutral` — для тонких строчных индикаторов рядом с текстом.
+- Host объявлен `role="status"` с `aria-live="polite"`: скринридер сообщит о появлении, не
+  перебивая чтение. Отдельной подписи компонент не даёт — если состояние важно назвать словами,
+  положи текст рядом.
+
+## Края
+
+- Вращение выключается у пользователей с `prefers-reduced-motion`. Проверять это в спеке нечем —
+  правило живёт в SCSS.
+
+## Рядом
+
+- [`rt-skeleton`](../skeleton/CONTEXT.md) — заглушка формы контента вместо кольца; для списков
+  и карточек она честнее спиннера.

package/src/lib/components/split-button/CONTEXT.md

@@ -0,0 +1,39 @@
+# `rt-split-button`
+
+Кнопка основного действия с прикреплённым меню дополнительных.
+
+```html
+<rt-split-button
+    label="Сохранить"
+    [menuItems]="[{ value: 'draft', label: 'Сохранить черновик' }]"
+    [loading]="saving()"
+    (faceClick)="save()"
+    (itemSelect)="run($event)" />
+```
+
+| вход                   | тип                                             | умолчание                    |
+| ---------------------- | ----------------------------------------------- | ---------------------------- |
+| `label`                | `string`                                        | **обязателен**               |
+| `menuItems`            | `readonly { value, label, icon?, disabled? }[]` | **обязателен**               |
+| `theme` / `size`       | как у [`[rtButton]`](../button/CONTEXT.md)      | `'primary'` / `'md'`         |
+| `menuAriaLabel`        | `string`                                        | `''` → `rtKit.uiMoreActions` |
+| `loading` / `disabled` | `boolean`                                       | `false`                      |
+
+Выходы: `faceClick`, `itemSelect` (значение пункта).
+
+## Главное, что нужно знать
+
+**Поповер висит на всём контроле, а не на узкой каретке.** Так ширина меню равна ширине кнопки, а
+левый край совпадает — иначе панель уезжала бы за экран.
+
+**Нажатие основной кнопки меню не открывает**, и наоборот: это два независимых действия.
+
+## Края
+
+- `loading` и `disabled` блокируют обе части и запрещают открытие меню.
+- Отключённый пункт не выбирается и меню не закрывает.
+- Значение пункта продублировано атрибутом `data-value`.
+
+## Рядом
+
+- [`rt-menu`](../menu/CONTEXT.md) — меню без основного действия.

package/src/lib/components/stat-tile/CONTEXT.md

@@ -0,0 +1,35 @@
+# `rt-stat-tile`
+
+Плитка показателя: значение, изменение к периоду, база сравнения.
+
+```html
+<rt-stat-tile
+    label="Визиты"
+    value="1 240"
+    secondary="из них 300 новых"
+    hint="Считается по уникальным"
+    [deltaPrimary]="{ percent: 12.5, label: 'к прошлой неделе', baseline: '1 100' }"
+    [deltaSecondary]="{ percent: 8, label: 'к прошлому году' }" />
+```
+
+| вход                              | тип                                     | умолчание       |
+| --------------------------------- | --------------------------------------- | --------------- |
+| `label` / `value`                 | `string`                                | **обязательны** |
+| `secondary`                       | `string \| null`                        | `null`          |
+| `hint`                            | `string \| null`                        | `null`          |
+| `deltaPrimary` / `deltaSecondary` | `{ percent, label, baseline? } \| null` | `null`          |
+
+Выходов нет.
+
+## Главное, что нужно знать
+
+**`percent: null` означает «сравнить не с чем» — и тогда изменение не рисуется вовсе.**
+Пустая плашка на его месте читалась бы как ноль. Ноль же — это `flat`: не рост и не падение.
+
+Знак и стрелка выводятся из числа: `> 0` — «+» и стрелка вверх, `< 0` — стрелка вниз. Дробная
+часть отделяется запятой.
+
+**Значение базы уходит параметром перевода, а не подставляется в готовую строку.** Transloco
+интерполирует `{{value}}` в момент перевода, и к возвращённой строке подставлять уже нечего:
+`String.replace` после `translateSignal` не находил плейсхолдера, и от подписи оставалась одна
+приставка («было», «was»). Параметр передан сигналом — смена базы переписывает строку.

package/src/lib/components/stat-tile/rt-stat-tile.component.scss

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

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

@@ -0,0 +1,36 @@
+# `rt-stepper`
+
+Полоса прогресса по шагам: точки, подпись текущего шага и его описание.
+
+```html
+<rt-stepper [steps]="[{ label: 'Заявка', description: 'Заполните данные' }, …]" [currentIndex]="1" />
+```
+
+| вход           | тип                                 | умолчание |
+| -------------- | ----------------------------------- | --------- |
+| `steps`        | `readonly { label, description }[]` | `[]`      |
+| `currentIndex` | `number \| string`                  | `0`       |
+
+Выходов нет — шаги переключает потребитель.
+
+## Главное, что нужно знать
+
+**Заполнение считается по промежуткам, а не по шагам.** Первый шаг даёт 0 %, последний — 100 %:
+при трёх шагах середина это 50 %. Единственный шаг всегда даёт 0 % — делить не на что.
+
+Номер шага за пределами набора зажимается **один раз, до всего остального**: и полоса, и якорь
+подписи, и объявление для скринридера читают уже зажатый индекс. Иначе показ и объявление
+расходятся — полоса упирается в 100 %, а на прогрессбаре оказывается `aria-valuenow` больше
+`aria-valuemax`, и подпись шага пропадает. Пустой набор объявляется нулём.
+
+## Края
+
+- Описание разбивается на абзацы по пустой строке (`\n\n`); пустое описание не создаёт абзаца.
+- Точки спрятаны от скринридера — прогресс он читает с самой полосы: `role="progressbar"`,
+  `aria-valuemin/max/now` и `aria-valuetext` с подписью текущего шага.
+- Подпись текущего шага прижимается к началу, центру или концу полосы в зависимости от того,
+  где стоит шаг.
+
+## Рядом
+
+- [`rt-timeline`](../timeline/CONTEXT.md) — журнал событий, а не линейный прогресс.

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

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

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

@@ -0,0 +1,53 @@
+# `rt-table`
+
+Таблица поверх CDK Table: колонки объявляются директивами CDK, а кит добавляет состояния,
+карточки для узкого экрана, меню строки и настройку колонок.
+
+```html
+<table rt-table tableId="tours" ariaLabel="Туры" [dataSource]="rows()" [columns]="columns" [loading]="loading()" [columnsConfig]="config">
+    <ng-container cdkColumnDef="title">
+        <th *cdkHeaderCellDef cdk-header-cell>Название</th>
+        <td *cdkCellDef="let row" cdk-cell>{{ row.title }}</td>
+    </ng-container>
+    <tr *cdkHeaderRowDef="columns" cdk-header-row></tr>
+    <tr *cdkRowDef="let row; columns: columns" cdk-row></tr>
+</table>
+```
+
+| вход                                | тип                           | умолчание     |
+| ----------------------------------- | ----------------------------- | ------------- |
+| `columns`                           | `ReadonlyArray<string>`       | `[]`          |
+| `columnsConfig`                     | `ReadonlyArray<ColumnConfig>` | `[]`          |
+| `tableId`                           | `string \| null`              | `null`        |
+| `density`                           | `'default' \| 'compact'`      | `'default'`   |
+| `cards`                             | `boolean`                     | `true`        |
+| `clickable`                         | `boolean`                     | `false`       |
+| `loading` / `fetching`              | `boolean`                     | `false`       |
+| `skeletonRows`                      | `number`                      | 5             |
+| `emptyMessage` / `emptyDescription` | `string` / `string \| null`   | `''` / `null` |
+| `emptyIcon`                         | `IRtIcon.Name \| null`        | `'inbox'`     |
+| `showRowActions`                    | `boolean`                     | `false`       |
+| `sort`                              | `ISortModel<string> \| null`  | `null`        |
+
+Выход: `sortChange`.
+
+## Главное, что нужно знать
+
+**`loading` и `fetching` — разные состояния.** Первая загрузка (`loading` при пустых данных)
+подменяет строки заглушками; догрузка (`fetching`) оставляет уже показанное на месте — иначе
+таблица мигала бы при каждой смене страницы.
+
+**Карточки — это другая разметка, а не перестроенная стилями таблица.** Компонент сам решает по
+ширине вьюпорта (`BreakpointsService.narrow`), что показать. Подписью в карточке служит **ключ
+колонки**: заголовки живут в шаблонах ячеек CDK, куда карточка не дотягивается. Осмысленные
+подписи даёт `columnsConfig`.
+
+**Настройка колонок требует и `columnsConfig`, и `tableId`.** Выбор хранится в IndexedDB, и без
+идентификатора таблицы его некуда положить — поэтому `canConfigure()` останется `false`.
+
+## Края
+
+- Пустой набор рисует заглушку с переведённым `rtKit.uiNoData`; свой текст перебивает её.
+- Колонка `rtRowActions` добавляется китом сама, когда включён `showRowActions`, и рисует
+  [`rt-menu`](../menu/CONTEXT.md) в строке.
+- Спеки логики лежат рядом: сортировка и предикат действий строки проверены отдельно.

package/src/lib/components/table/settings-aside/rt-table-settings-aside.component.scss

@@ -1,5 +1,7 @@
 /* rt-table-settings-aside — ViewEncapsulation.None (common/ui). Своей раскладки нет:
-   chrome даёт rt-aside, тело — rt-table-settings-panel. */
-:host {
+   chrome даёт rt-aside, тело — rt-table-settings-panel. `.rt-table-settings-aside` —
+   сам хост, и он не должен добавлять бокс между асайдом и его местом в overlay. */
+
+.rt-table-settings-aside {
     display: contents;
 }

package/src/lib/components/table/settings-panel/rt-table-settings-panel.component.scss

@@ -1,5 +1,5 @@
 /* rt-table-settings-panel — ViewEncapsulation.None (common/ui): правила таргетируют
-   BEM-класс глобально, без :host-обёртки (как rt-icon / rt-dialog-footer). */
+   BEM-класс блока, как во всём ките. */
 .rt-table-settings-panel {
     &__list {
         display: flex;

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

@@ -0,0 +1,56 @@
+# `rt-tabs` + `[rtTab]`
+
+Вкладки объявляются директивой на `<ng-template>` — содержимое неактивной вкладки не создаётся.
+
+```html
+<rt-tabs stretch [activeId]="tab()" (activeIdChange)="tab.set($event)">
+    <ng-template rtTab="main" label="Основное">…</ng-template>
+    <ng-template rtTab="extra" label="Дополнительно" [badge]="3">…</ng-template>
+    <ng-template rtTab="docs" label="Документы" icon="file" [invalid]="hasErrors()">…</ng-template>
+</rt-tabs>
+```
+
+## `rt-tabs`
+
+| вход                | тип                          | умолчание      |
+| ------------------- | ---------------------------- | -------------- |
+| `activeId`          | `IRtTabs.Id \| null`         | `null`         |
+| `direction`         | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `stretch`           | `boolean`                    | `false`        |
+| `contentScrollable` | `boolean`                    | `true`         |
+
+Выход: `activeIdChange: IRtTabs.Id`.
+
+## `[rtTab]`
+
+| вход                              | тип                                           | умолчание                   |
+| --------------------------------- | --------------------------------------------- | --------------------------- |
+| `rtTab`                           | `IRtTabs.Id` — идентификатор вкладки          | `''`                        |
+| `label`                           | `string`                                      | `''`                        |
+| `titleTemplate`                   | `TemplateRef \| null`                         | `null`                      |
+| `icon` / `iconColor`              | `IRtIcon.Name \| null` / `IRtTabs.TitleColor` | `null` / `'current'`        |
+| `badge`                           | `string \| number \| null`                    | `null`                      |
+| `disabled` / `hidden` / `invalid` | `boolean`                                     | `false`                     |
+| `invalidMessage`                  | `string`                                      | `''` → `rtKit.uiTabInvalid` |
+
+## Главное, что нужно знать
+
+**Вход `activeId` необязателен.** Без него компонент помнит выбор сам — управляемый режим нужен
+только когда вкладка лежит в адресе страницы.
+
+**Идентификатор, которого нет, откатывается на первую доступную вкладку.** То же с отключённой:
+активной она стать не может. Так вкладка из старой ссылки не оставляет пустой экран.
+
+## Клавиатура и доступность
+
+- Стрелки (влево/вправо, а в вертикальной раскладке вверх/вниз) перешагивают отключённые вкладки
+  и заворачиваются по кругу; `Home`/`End` — к первой и последней.
+- В таб-порядке стоит **только активная** вкладка (`tabindex="0"`), остальные достаются стрелками.
+- Панель и вкладка связаны в обе стороны: `aria-controls` ↔ `aria-labelledby`.
+
+## Края
+
+- `hidden` убирает вкладку из шапки целиком; `disabled` оставляет её видимой, но некликабельной.
+- У невалидной вкладки появляется подсказка с текстом `invalidMessage`.
+- Стрелки прокрутки шапки есть в разметке всегда — показывает их модификатор `--visible`,
+  который выставляется по замеру ширины после отрисовки.