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

package/src/lib/components/file-input/CONTEXT.md

@@ -0,0 +1,36 @@
+# `rt-file-input`
+
+Поле выбора файлов: кнопка, скрытое нативное поле и список выбранного карточками.
+
+```html
+<rt-field label="Документы">
+    <rt-file-input accept=".pdf,.docx" buttonLabel="Прикрепить" [formControl]="docs" [multiple]="true" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход          | тип              | умолчание                   |
+| ------------- | ---------------- | --------------------------- |
+| `multiple`    | `boolean`        | `false`                     |
+| `accept`      | `string \| null` | `null`                      |
+| `directory`   | `boolean`        | `false`                     |
+| `buttonLabel` | `string`         | `''` → `rtKit.uiChooseFile` |
+
+Значение — `File[]`.
+
+## Главное, что нужно знать
+
+**Нативное поле спрятано.** Его нельзя оформить, поэтому выбор открывает своя кнопка, кликая по
+скрытому полю программно.
+
+**Без `multiple` берётся только первый файл**, даже если браузер отдал набор: так бывает при
+перетаскивании в одиночное поле.
+
+**Удаление файла сбрасывает значение нативного поля.** Иначе повторный выбор того же файла не
+дал бы события `change`.
+
+## Рядом
+
+- [`rt-file-drop`](../file-drop/CONTEXT.md) — приём файлов перетаскиванием.
+- [`rt-file-card`](../file-card/CONTEXT.md) — чем рисуется каждый выбранный файл.

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

@@ -0,0 +1,15 @@
+# `rt-file-list`
+
+Раскладка перечня файлов. Входов, выходов и своей разметки нет — только отступы и перенос.
+
+```html
+<rt-file-list>
+    <rt-file-card *ngFor="…" … />
+</rt-file-list>
+```
+
+## Главное, что нужно знать
+
+**Это чистая раскладка.** Что показывать — карточки [`rt-file-card`](../file-card/CONTEXT.md),
+ссылки [`rt-download-link`](../download-link/CONTEXT.md) или свои строки — решает потребитель.
+Пустоту и загрузку тоже рисует он: у списка нет ни заглушки, ни состояния.

package/src/lib/components/filter-control/CONTEXT.md

@@ -0,0 +1,33 @@
+# `rt-filter-control<T>`
+
+Фильтр, который сам выбирает представление по ширине экрана.
+
+```html
+<rt-filter-control ariaLabel="Статус" [options]="options" [value]="status()" (valueChange)="status.set($event)" />
+```
+
+| вход                     | тип                                              | умолчание      |
+| ------------------------ | ------------------------------------------------ | -------------- |
+| `options`                | `ReadonlyArray<{ value, label, icon?, title? }>` | **обязателен** |
+| `value`                  | `T \| undefined`                                 | `undefined`    |
+| `ariaLabel`              | `string \| null`                                 | `null`         |
+| `placeholder`            | `string`                                         | `''`           |
+| `size`                   | `'sm' \| 'md' \| 'lg'`                           | `'sm'`         |
+| `disabled` / `fullWidth` | `boolean`                                        | `false`        |
+
+Выход: `valueChange`.
+
+## Главное, что нужно знать
+
+**Одно и то же наполнение рисуется двумя разными контролами.** На широком экране это
+[`rt-toggle-button-group`](../toggle-button-group/CONTEXT.md), на узком (≤1080px, по
+`BreakpointsService.narrow`) — [`rt-select`](../select/CONTEXT.md): сегменты в строку не
+помещаются. Потребитель об этом не думает и передаёт один набор.
+
+**Очистка списка выключена**: фильтр всегда в каком-то состоянии, «ничего не выбрано» здесь не
+предусмотрено.
+
+## Края
+
+- Иконки вариантов доезжают только до сегментов; в списке остаются одни подписи.
+- Отключение доходит до обоих представлений.

package/src/lib/components/form-control/CONTEXT.md

@@ -0,0 +1,50 @@
+# `RtFormControlBase<TValue>`
+
+Абстрактная основа всех полей ввода кита. Собственной разметки не имеет и в разметку не ставится —
+от неё наследуются [`rt-input`](../input/CONTEXT.md), [`rt-textarea`](../textarea/CONTEXT.md),
+[`rt-input-number`](../input-number/CONTEXT.md), [`rt-select`](../select/CONTEXT.md),
+[`rt-multiselect`](../multiselect/CONTEXT.md), [`rt-autocomplete`](../autocomplete/CONTEXT.md),
+[`rt-date-picker`](../date-picker/CONTEXT.md).
+
+Общие входы, которые получает каждый наследник:
+
+| вход        | тип                    | умолчание |
+| ----------- | ---------------------- | --------- |
+| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`    |
+| `disabled`  | `boolean`              | `false`   |
+| `controlId` | `string \| null`       | `null`    |
+| `ariaLabel` | `string \| null`       | `null`    |
+| `clearable` | `boolean`              | `true`    |
+| `bordered`  | `boolean`              | `true`    |
+
+## Главное, что нужно знать
+
+**`NgControl` инжектится самим полем (`{ self: true, optional: true }`), а `valueAccessor`
+привязывается вручную — провайдера `NG_VALUE_ACCESSOR` здесь нет.** Так поле получает доступ к
+`control.invalid` / `touched` / `errors` (и умеет подсвечивать ошибку и отдавать её текст в
+[`rt-field`](../field/CONTEXT.md)), не создавая цикла самоссылки, на котором Angular падает
+с NG0200.
+
+**Подсветка ошибки включается только после касания или правки**: `invalid && (touched || dirty)`.
+Пустое обязательное поле невалидно с самого начала, но краснеть до первого касания не должно.
+
+## Что задаёт вмещающее поле, а не потребитель
+
+`rt-field` вызывает у контрола три метода — руками их звать не нужно:
+
+- `assignControlId(id)` — авто-идентификатор для связки `label[for]`, если у контрола нет своего;
+- `setReadonly(value)` — плоский режим чтения (`isReadonly`), в котором контрол подменяется
+  текстом `displayText()`;
+- читает `required()`, `invalid()`, `errors()` — для звёздочки и текста ошибки.
+
+## Что обязан реализовать наследник
+
+| член                | зачем                                           |
+| ------------------- | ----------------------------------------------- |
+| `getEmptyValue()`   | пустое значение своего типа: `''`, `null`, `[]` |
+| `hasValue`          | есть ли что очищать — гейт видимости крестика   |
+| `focusAfterClear()` | куда вернуть фокус после очистки                |
+| `displayText`       | текст плоского режима чтения                    |
+
+Поля с отдельным состоянием отображения (`rt-autocomplete`, `rt-input-number`) вдобавок
+переопределяют `writeValue` и `clearValue`, синхронизируя свой сигнал отображения.

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

@@ -0,0 +1,36 @@
+# `rt-header`
+
+Верхняя полоса приложения: кнопка «назад», логотип, приглашение, колокольчик и профиль.
+
+```html
+<rt-header showInvite [canGoBack]="canGoBack()" (backClick)="back()" (inviteClick)="invite()" (profileClick)="openProfile()">
+    <rt-notifications-bell rtHeaderBell [unread]="hasUnread()" (clicked)="openNotifications()" />
+</rt-header>
+```
+
+| вход         | тип       | умолчание |
+| ------------ | --------- | --------- |
+| `canGoBack`  | `boolean` | `false`   |
+| `showInvite` | `boolean` | `false`   |
+
+Выходы: `backClick`, `inviteClick`, `profileClick`. Слот `[rtHeaderBell]` — колокольчик.
+
+## Главное, что нужно знать
+
+**Кнопка «назад» не появляется и не исчезает — она проявляется.** Узел есть в разметке всегда,
+видимость даёт модификатор `rt-header__back--visible`: иначе соседние элементы шапки прыгали бы
+при каждом переходе.
+
+**Колокольчик приходит проекцией.** Шапка ничего не знает про уведомления — их состоянием
+владеет приложение.
+
+## Края
+
+- Кнопки действий подогнаны под высоту шапки инлайновым `--rt-icon-button-size: 35px` — это
+  осознанный выход за шкалу размеров.
+- Логотип рисуется вариантом `wordmark` высотой 15px; сами файлы даёт приложение
+  (см. [`rt-logo`](../logo/CONTEXT.md)).
+
+## Рядом
+
+- [`rt-page-header`](../page-header/CONTEXT.md) — вторая полоса, с разделами.

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

@@ -0,0 +1,46 @@
+# `rt-icon`
+
+```html
+<rt-icon name="check" size="md" color="current" [rotate]="null" />
+```
+
+| вход     | тип                                                                                 | умолчание      |
+| -------- | ----------------------------------------------------------------------------------- | -------------- |
+| `name`   | `IRtIcon.Name` — литеральный union из `rt-icon-names.ts`                            | **обязателен** |
+| `size`   | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                     | `'md'`         |
+| `color`  | `'current' \| 'muted' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'inverse'` | `'current'`    |
+| `rotate` | `number \| string \| null`                                                          | `null`         |
+
+Выходов нет. Размер и цвет едут инлайновым стилем host-а (`width`/`height`/`color`), не классом:
+`xs` 12px, `sm` 16px, `md` 20px, `lg` 24px, `xl` 32px, `2xl` 40px.
+
+## Главное, что нужно знать
+
+**Компонент ничего не грузит.** Он рисует `<use href="#rt-icon-<name>">` — ссылку на symbol
+внутри спрайта, который собирает `RtIconRegistry` и вставляет в `<body>`
+провайдер `provideRtIcons()`. Без этого провайдера разметка верна, а на экране пусто.
+
+Приложение обязано опубликовать набор из `assets/icons` пакета по адресу, который знает реестр
+(по умолчанию `/icons`, иначе `provideRtIcons('/my/icons')`).
+
+## Как этим пользоваться
+
+- Иконка спрятана от скринридера (`aria-hidden="true"`) — подпись даёт вмещающий её контрол.
+  Отдельная `rt-icon` без подписи для AT невидима, и это правильно.
+- Цвет по умолчанию наследуется от текста. Явное значение нужно, только когда иконка должна
+  отличаться от текста своего контрола.
+- `rotate` принимает строку (`rotate="180"`) — так значение приходит из атрибута разметки.
+  Ноль и нечисловая строка гасят поворот: лишний `transform` создавал бы отдельный слой отрисовки.
+
+## Края
+
+- **Имя без файла роняет весь набор.** Реестр собирает спрайт одним `forkJoin`; один отказ
+  гасит иконки во всём приложении. Добавляя имя в `rt-icon-names.ts`, положи SVG рядом.
+- Реестр пропускает загрузку, если спрайт уже в DOM (`#rt-icon-sprite`) — так витрина не гоняет
+  сотни запросов между историями.
+- На сервере (SSR) спрайт не грузится: относительных HTTP-запросов к статике там нет, иконки
+  дорисуются после гидрации.
+
+## Рядом
+
+- [`rt-icon-button`](../icon-button/CONTEXT.md) — кликабельная иконка с подписью для AT.

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

@@ -1,8 +1,6 @@
-/* rt-icon — глобальные правила компонента (ViewEncapsulation.None).
-   Намеренно без :host-обёртки: правила должны таргетировать `.rt-icon` глобально
-   (host-класс компонента + потенциальные программные потребители sprite'а).
-   Это исключение из общего правила "обёртывать стили в :host", применимого
-   только для Emulated-инкапсуляции. */
+/* rt-icon — правила компонента (ViewEncapsulation.None).
+   Селектор bare `.rt-icon` (класс на host) — им же адресуются и программные
+   потребители sprite'а, рисующие иконку без компонента. */
 .rt-icon {
     display: inline-flex;
     flex-shrink: 0;

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

@@ -0,0 +1,49 @@
+# `rt-icon-button`
+
+```html
+<rt-icon-button icon="ico-trash" ariaLabel="Удалить" variant="danger" size="md" (clicked)="remove()" />
+```
+
+| вход                                            | тип                                                                         | умолчание                    |
+| ----------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
+| `icon`                                          | `IRtIcon.Name`                                                              | **обязателен**               |
+| `ariaLabel`                                     | `string`                                                                    | **обязателен**               |
+| `variant`                                       | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'success' \| 'warning'` | `'ghost'`                    |
+| `size`                                          | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                     | `'md'`                       |
+| `iconSize`                                      | `IRtIcon.Size \| null`                                                      | `null` → от размера кнопки   |
+| `iconColor`                                     | `IRtIcon.Color`                                                             | `'current'`                  |
+| `shape`                                         | `'circle' \| 'square'`                                                      | `'square'`                   |
+| `type`                                          | `'button' \| 'submit'`                                                      | `'button'`                   |
+| `tooltip`                                       | `string`                                                                    | `''` (пусто → подсказки нет) |
+| `tabIndex`                                      | `number`                                                                    | `0`                          |
+| `loading` / `disabled` / `active` / `indicator` | `boolean`                                                                   | `false`                      |
+
+| выход     | тип          |
+| --------- | ------------ |
+| `clicked` | `MouseEvent` |
+
+## Главное, что нужно знать
+
+**`ariaLabel` обязателен.** У кнопки нет текста, и без подписи она для скринридера безымянна.
+Это единственная причина, по которой вход помечен `required`.
+
+**Кнопку компонент рисует внутри себя**, host остаётся обычным элементом. Диаметр держит
+свойство `--rt-icon-button-size`, и объявляет его модификатор размера на самой кнопке —
+поэтому ни класс на host-е, ни инлайн-стиль на нём диаметра не меняют: собственное
+объявление элемента бьёт унаследованное. Размер вне шкалы получается не обходом, а новой
+ступенью здесь же: `sm` 28px, `md` 36px, `lg` 44px, `xl` 52px, `2xl` 60px.
+
+## Как этим пользоваться
+
+- `loading` = `disabled` плюс кольцо вместо иконки. Клик в этом состоянии наружу не уходит.
+- `active` превращается в `aria-pressed="true"` — для кнопок-переключателей.
+- `tabIndex="-1"` оставляет клик мышью, но убирает кнопку из таб-порядка: так сделаны
+  вспомогательные крестики внутри полей.
+- `iconSize` нужен, когда крупная кнопка должна остаться крупной (в неё целятся пальцем), а
+  иконка во весь диаметр выглядит тяжеловесно.
+- Модификаторы в камелкейсе конвертируются в дефис: `indicator` → `rt-icon-button--has-indicator`.
+
+## Рядом
+
+- [`[rtButton]`](../button/CONTEXT.md) — кнопка с подписью.
+- [`[rtTooltip]`](../tooltip/CONTEXT.md) — то, чем рисуется вход `tooltip`.

package/src/lib/components/icon-button/rt-icon-button.component.scss

@@ -1,4 +1,9 @@
-:host {
+/* rt-icon-button — иконочная кнопка в common/ui. ViewEncapsulation.None.
+   Хост адресуется по имени элемента, а не по классу блока: класс `.rt-icon-button` висит
+   и на `<rt-icon-button>`, и на корне шаблона, поэтому правила блока вложены в хост —
+   так они достаются только корню шаблона. */
+
+rt-icon-button {
     display: inline-flex;
 
     /* Дефолт = md; перезаписывается модификаторами sm/lg ниже либо inline стилем потребителя */
@@ -30,6 +35,14 @@
             --rt-icon-button-size: 44px;
         }
 
+        &--xl {
+            --rt-icon-button-size: 52px;
+        }
+
+        &--2xl {
+            --rt-icon-button-size: 60px;
+        }
+
         &--circle {
             border-radius: var(--rt-radius-full);
         }

package/src/lib/components/info-item/CONTEXT.md

@@ -0,0 +1,30 @@
+# `rt-info-item`
+
+```html
+<rt-info-item label="Тариф" [loading]="!plan()" [grow]="true">{{ plan()?.title }}</rt-info-item>
+```
+
+| вход      | тип       | умолчание      |
+| --------- | --------- | -------------- |
+| `label`   | `string`  | **обязателен** |
+| `loading` | `boolean` | `false`        |
+| `grow`    | `boolean` | `false`        |
+
+Значение приходит **проекцией**, а не входом — поэтому внутрь можно положить что угодно:
+текст, `rt-tag`, ссылку, `@if`.
+
+## Главное, что нужно знать
+
+**Во время загрузки подменяется только значение.** Подпись остаётся на месте: по ней читается,
+чего именно ждут. Заглушка узкая (80px) — под значение, а не под всю строку.
+
+## Как этим пользоваться
+
+- `grow` растягивает элемент по свободному месту строки. Без него он занимает свою ширину —
+  так пары «подпись: значение» выстраиваются в ряд.
+- Пара подпись/значение — самостоятельный блок; для длинного вертикального перечня
+  «ключ → значение» есть [`rt-detail-list`](../detail-list/CONTEXT.md).
+
+## Рядом
+
+- [`rt-skeleton-wrapper`](../skeleton-wrapper/CONTEXT.md) — то, чем нарисована заглушка.

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

@@ -0,0 +1,47 @@
+# `rt-input`
+
+```html
+<rt-field label="Имя">
+    <rt-input placeholder="Как в паспорте" iconLeft="search" [formControl]="name" />
+</rt-field>
+
+<rt-input type="password" [formControl]="password" [passwordToggle]="true" />
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md)
+(`size`, `disabled`, `controlId`, `ariaLabel`, `clearable`, `bordered`):
+
+| вход                     | тип                                         | умолчание |
+| ------------------------ | ------------------------------------------- | --------- |
+| `type`                   | `'text' \| 'password' \| 'email' \| 'time'` | `'text'`  |
+| `placeholder`            | `string`                                    | `''`      |
+| `iconLeft` / `iconRight` | `IRtIcon.Name \| null`                      | `null`    |
+| `passwordToggle`         | `boolean`                                   | `false`   |
+| `autocomplete`           | `string \| null`                            | `null`    |
+
+Значение — `string`.
+
+## Главное, что нужно знать
+
+**Крестик очистки и переключатель пароля делят один постфикс.** На поле пароля с включённым
+переключателем крестика не будет: показать оба некуда.
+
+Крестик показывается при выполнении трёх условий сразу: `clearable` (по умолчанию включён),
+в поле есть значение, поле не отключено. Из таб-порядка он исключён (`tabindex="-1"`) — до
+вспомогательного аффорданса не должны доходить табом.
+
+## Как этим пользоваться
+
+- `type="time"` заведён намеренно: браузер сам отдаёт `HH:MM` и раскладку под локаль, а разбор
+  строки руками означал бы своё поле ввода времени рядом с китом.
+- Клик по рамке (падинги принадлежат host-у, а не `<input>`) переводит фокус в поле — кроме
+  кликов по самому полю и по интерактивному постфиксу.
+- Режим плоского чтения включает **вмещающий [`rt-field`](../field/CONTEXT.md)**, а не вход
+  компонента: `[readonly]` стоит на поле-обёртке. Пустое значение в этом режиме рисуется прочерком.
+- Подсветка ошибки (`rt-input--invalid`) включается сама после касания — см. основу полей.
+
+## Рядом
+
+- [`rt-field`](../field/CONTEXT.md) — подпись, звёздочка, текст ошибки, режим чтения.
+- [`rt-input-number`](../input-number/CONTEXT.md) — для чисел с группировкой разрядов.
+- [`rt-autocomplete`](../autocomplete/CONTEXT.md) — поле с подсказками.

package/src/lib/components/input-number/CONTEXT.md

@@ -0,0 +1,52 @@
+# `rt-input-number`
+
+```html
+<rt-field label="Сумма">
+    <rt-input-number prefix="₽" [formControl]="amount" [min]="0" [max]="1000000" [maxFractionDigits]="2" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход                | тип                    | умолчание                      |
+| ------------------- | ---------------------- | ------------------------------ |
+| `prefix`            | `string \| null`       | `null`                         |
+| `iconLeft`          | `IRtIcon.Name \| null` | `null`                         |
+| `placeholder`       | `string`               | `''`                           |
+| `min` / `max`       | `number \| null`       | `null` (сторона не ограничена) |
+| `minFractionDigits` | `number`               | `0`                            |
+| `maxFractionDigits` | `number`               | `2`                            |
+
+Значение — `number | null`.
+
+## Главное, что нужно знать
+
+**Точность фиксирована, а не задана диапазоном.** Итоговое число знаков —
+`max(minFractionDigits, min(maxFractionDigits, 20))`, и одно и то же значение служит и нижней, и
+верхней границей. С умолчаниями это значит: `12` после ухода фокуса становится `12,00`. Целое
+поле — это `maxFractionDigits: 0`.
+
+**Разбор и запись зависят от локали (`LOCALE_ID`) и обязаны сходиться.** Разделитель разрядов
+берётся у локали, и разбор снимает именно его: `1 234,56` в `ru`, `1,234.56` в `en-US`.
+Разделителем дробной части считается только тот знак из «`.`», «`,`», которым в этой локали не
+разделяются разряды, — поэтому в `ru` годятся оба, а в `en-US` запятая всегда читается как
+разряды. Локаль-слепой разбор здесь и ломался: безусловная замена первой запятой на точку
+превращала показанное `1,000` в `1`.
+
+## Как этим пользоваться
+
+- Это `<input type="text" inputmode="decimal">`, а не `type="number"`: у нативного числового поля
+  колесо мыши меняет значение, а разделители зависят от браузера.
+- Во время набора разряды группируются на лету, а каретка удерживается на месте (позиция
+  пересчитывается по числу значимых символов слева от неё).
+- Нечисловой ввод стрипается из отображения, но **прежнее значение держится до ухода фокуса** —
+  наружу оно не уходит. Пустое поле пишет `null`.
+- На уходе фокуса значение зажимается в границы, округляется до точности и переписывается
+  отформатированным.
+- **Крестик обнуляет поле, а не опустошает его** (`0,00`): у числового поля ноль осмыслен.
+  При нуле крестик не показывается — обнулять больше нечего.
+- Префикс спрятан от скринридера: валюту он прочитает из подписи поля.
+
+## Рядом
+
+- [`rt-counter`](../counter/CONTEXT.md) — когда число меняют шагами, а не набирают.

package/src/lib/components/live-badge/CONTEXT.md

@@ -0,0 +1,31 @@
+# `rt-live-badge`
+
+```html
+<rt-live-badge label="Смотрят сейчас" [count]="visitors()" [active]="streamAlive()" />
+```
+
+| вход     | тип              | умолчание                                |
+| -------- | ---------------- | ---------------------------------------- |
+| `label`  | `string`         | `''` → переведённое `rtKit.uiLiveOnSite` |
+| `count`  | `number \| null` | `null` → прочерк `—`                     |
+| `active` | `boolean`        | `false`                                  |
+
+Выходов нет.
+
+## Главное, что нужно знать
+
+**`active` означает «поток жив», а не «счётчик больше нуля».** Ноль посетителей при живом
+потоке — это данные; оборванный поток — их отсутствие, и выглядеть они должны по-разному.
+Поэтому `[active]="true"` с `[count]="0"` — законное состояние, а `count === null` рисует
+прочерк, а не ноль.
+
+## Как этим пользоваться
+
+- Пустая подпись равна отсутствию входа: подставляется переведённая формулировка кита.
+  Значит `[label]="maybeEmpty()"` безопасно.
+- Живость дублируется атрибутом `data-active` — по нему бейдж находят проверки, не завязываясь
+  на BEM-класс.
+
+## Рядом
+
+- [`rt-tag`](../tag/CONTEXT.md) — статусная пилюля без счётчика.

package/src/lib/components/live-badge/rt-live-badge.component.scss

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

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

@@ -0,0 +1,42 @@
+# `rt-logo`
+
+```html
+<rt-logo variant="lockup" ariaLabel="Панель управления" [height]="75" [aspect]="0" />
+```
+
+| вход        | тип                      | умолчание                |
+| ----------- | ------------------------ | ------------------------ |
+| `variant`   | `'wordmark' \| 'lockup'` | `'lockup'`               |
+| `height`    | `number \| string` (px)  | `0` → умолчание варианта |
+| `aspect`    | `number \| string`       | `0` → умолчание варианта |
+| `ariaLabel` | `string`                 | `''`                     |
+
+Умолчания: `wordmark` — 51px высотой при отношении 5.4; `lockup` — 75px при 3.6.
+Ширина считается как `round(height × aspect)`.
+
+## Главное, что нужно знать
+
+**Начертания кит не везёт.** Их даёт приложение четырьмя свойствами оформления на любом предке:
+
+```css
+:root {
+    --rt-logo-wordmark: url('/logo/wordmark.svg');
+    --rt-logo-wordmark-dark: url('/logo/wordmark-inverse.svg');
+    --rt-logo-tagline: url('/logo/tagline.svg');
+    --rt-logo-tagline-dark: url('/logo/tagline-inverse.svg');
+}
+```
+
+Пока свойства не заданы, компонент занимает место и не рисует ничего. Это ожидаемое состояние,
+а не сбой.
+
+Начертания лежат фоном, а не в `<img>`, потому что у тёмной темы своя пара файлов, и подмена
+`background-image` — единственный способ переключить их одним правилом.
+
+## Края
+
+- **Ноль в `height`/`aspect` означает «не задано», а не нулевой размер.** Числовой вход иначе не
+  отличает одно от другого.
+- `aspect` нужен, если пропорции своего файла не совпадают с умолчанием: ширину host-а кит
+  считает сам и чужих пропорций не знает — логотип обрежется или обрастёт пустотой.
+- Подпись для скринридера задаёт приложение: названия продукта кит не знает.

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

@@ -8,12 +8,10 @@
  * лежат фоном, а не в <img>: у тёмной темы своя пара файлов, и подмена
  * background-image — единственный способ переключить их одним правилом.
  */
-:host {
+.rt-logo {
     display: inline-block;
     line-height: 0;
-}
 
-.rt-logo {
     &__wordmark,
     &__tagline {
         display: block;
@@ -48,17 +46,17 @@
 /* Композиция lockup: начертание и слоган стоят колонкой и делят высоту host'а.
    Пропорция та же, что у пары в макете: ~66.7% начертанию, ~22.1% слогану,
    остальное — зазор между ними. */
-:host:has(.rt-logo__tagline) {
+.rt-logo:has(.rt-logo__tagline) {
     display: flex;
     flex-direction: column;
     align-items: stretch;
     justify-content: space-between;
 }
 
-:host:has(.rt-logo__tagline) .rt-logo__wordmark {
+.rt-logo:has(.rt-logo__tagline) .rt-logo__wordmark {
     height: 66.7%;
 }
 
-:host:has(.rt-logo__tagline) .rt-logo__tagline {
+.rt-logo:has(.rt-logo__tagline) .rt-logo__tagline {
     height: 22.1%;
 }

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

@@ -0,0 +1,65 @@
+# `rt-menu` + `rt-menu-item`
+
+Меню действий: иконочная кнопка, раскрывающая список пунктов.
+
+```html
+<rt-menu ariaLabel="Действия со строкой" align="end">
+    <rt-menu-item label="Открыть" icon="ico-eye" (selected)="open()" />
+    <rt-menu-item
+        label="Удалить"
+        icon="ico-trash"
+        confirmMessage="Удалить запись? Действие необратимо."
+        confirmTitle="Удаление"
+        [danger]="true"
+        (selected)="remove()" />
+</rt-menu>
+```
+
+## `rt-menu`
+
+| вход        | тип                | умолчание                |
+| ----------- | ------------------ | ------------------------ |
+| `icon`      | `IRtIcon.Name`     | `'ellipsis-h'`           |
+| `ariaLabel` | `string`           | `''` → `rtKit.uiActions` |
+| `align`     | `'start' \| 'end'` | `'end'`                  |
+| `disabled`  | `boolean`          | `false`                  |
+
+## `rt-menu-item`
+
+| вход                                  | тип                                  | умолчание                         |
+| ------------------------------------- | ------------------------------------ | --------------------------------- |
+| `label`                               | `string`                             | `''`                              |
+| `icon`                                | `IRtIcon.Name \| null`               | `null`                            |
+| `danger` / `disabled`                 | `boolean`                            | `false`                           |
+| `tooltip`                             | `string`                             | — (через `[rtTooltip]` на host-е) |
+| `confirmMessage`                      | `string`                             | `''`                              |
+| `confirmTitle`                        | `string \| null`                     | `null`                            |
+| `confirmLabel` / `confirmCancelLabel` | `string`                             | `''` → словарь кита               |
+| `confirmTone`                         | `'danger' \| 'warning' \| 'primary'` | `'danger'`                        |
+
+| выход      | тип    |
+| ---------- | ------ |
+| `selected` | `void` |
+
+## Главное, что нужно знать
+
+**Пункт не знает о меню.** Выбрав себя, он бросает всплывающее событие `rtMenuSelect`, а панель
+закрывается, поймав его. Благодаря этому пункт остаётся самостоятельным и его можно завернуть
+в свой компонент — лишь бы событие всплывало.
+
+**Подтверждение у пункта — диалог, а не поповер.** Панель поповера крепится к пункту, а пункт
+исчезает вместе с закрывшимся меню — держаться панели было бы не на чем. Поэтому
+`confirmMessage` открывает `rt-menu-confirm-dialog`, и `selected` приходит **только** после
+подтверждения.
+
+## Края
+
+- Отключённый пункт не выбирается и меню не закрывает: он выпадает из таб-порядка (`tabindex`
+  снимается) и помечается `aria-disabled`.
+- Enter и Space на пункте работают как клик.
+- Панель объявлена `role="menu"`, пункт — `role="menuitem"`.
+
+## Рядом
+
+- [`[rtConfirm]`](../confirm-popover/CONTEXT.md) — подтверждение под обычной кнопкой.
+- [`rt-split-button`](../split-button/CONTEXT.md) — кнопка с прикреплённым меню.