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

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

@@ -0,0 +1,72 @@
+# `rt-field`
+
+Обёртка единой анатомии поля: подпись сверху, контрол посередине, подсказка или ошибка снизу.
+
+```html
+<rt-field label="Имя" hint="Как в паспорте" help="Совпадает с документом" [errors]="{ required: 'Без имени не пустим' }">
+    <rt-input [formControl]="name" />
+</rt-field>
+
+<rt-field label="Комментарий">
+    <rt-textarea [formControl]="comment" />
+    <span rtFieldHint>
+        Не короче
+        <strong>трёх</strong>
+        символов
+    </span>
+</rt-field>
+```
+
+| вход               | тип                            | умолчание |
+| ------------------ | ------------------------------ | --------- |
+| `label`            | `string`                       | `''`      |
+| `hint`             | `string`                       | `''`      |
+| `help`             | `string`                       | `''`      |
+| `errors`           | `Record<validatorKey, string>` | `{}`      |
+| `readonly`         | `boolean`                      | `false`   |
+| `loading`          | `boolean`                      | `false`   |
+| `hideRequiredMark` | `boolean`                      | `false`   |
+| `reserveHintSpace` | `boolean`                      | `false`   |
+
+## Главное, что нужно знать
+
+**Поле само находит контрол** через `contentChild(RtFormControlBase)` — достаточно положить любой
+контрол кита внутрь. Дальше оно:
+
+- выдаёт контролу авто-идентификатор (`rt-field-N`) и связывает с ним `<label for>`, если у
+  контрола нет своего `controlId`;
+- рисует «\*», если у контрола есть валидатор обязательности (обнаруживается сам, входа для этого
+  нет);
+- показывает текст ошибки и включает режим плоского чтения.
+
+Всё это работает только для контролов кита. Обычный `<input>` внутрь класть можно, но подписи,
+звёздочки и ошибки он не получит.
+
+## Ошибки
+
+Показывается **одно** сообщение — первого сработавшего валидатора. Текст берётся так:
+
+1. `errors[имяВалидатора]`, переданный формой;
+2. переведённое умолчание кита (`required`, `email`, `minlength`, `maxlength`, `min`, `max`,
+   `pattern`);
+3. пусто, если валидатор незнаком и своего текста нет.
+
+Ошибка появляется только после касания или правки контрола — это решает сам контрол, а не поле.
+
+## Подсказка
+
+- Строковый `[hint]` — обычный случай.
+- Проекция `[rtFieldHint]` — когда подсказке нужна разметка; она **важнее** строкового входа.
+- Без резерва подсказка уступает место ошибке. С `reserveHintSpace` она остаётся в потоке, но
+  прячется от скринридера (`aria-hidden`), а высота строки перестаёт скакать при появлении ошибки.
+
+## Края
+
+- `hideRequiredMark` нужен формам, где обязательны все поля и звёздочка становится шумом.
+- `loading` оборачивает **только зону контрола** в заглушку; подпись и подсказка остаются
+  видимыми — по ним читается, чего ждут.
+- Текст пояснения (`help`) живёт в поповере и до наведения не отрисован.
+
+## Рядом
+
+- [`RtFormControlBase`](../form-control/CONTEXT.md) — что именно поле читает у контрола.

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

@@ -0,0 +1,28 @@
+# `rt-file-card`
+
+Карточка файла: иконка по типу, имя, размер и необязательные действия.
+
+```html
+<rt-file-card name="Договор.pdf" size="md" showDownload showRemove [sizeBytes]="204800" (download)="save()" (removed)="detach()" />
+```
+
+| вход                                         | тип                    | умолчание      |
+| -------------------------------------------- | ---------------------- | -------------- |
+| `name`                                       | `string`               | **обязателен** |
+| `sizeBytes`                                  | `number \| null`       | `null`         |
+| `size`                                       | `'sm' \| 'md' \| 'lg'` | `'md'`         |
+| `showDownload` / `showRename` / `showRemove` | `boolean`              | `false`        |
+| `disabled`                                   | `boolean`              | `false`        |
+
+Выходы: `download`, `rename`, `removed`.
+
+## Главное, что нужно знать
+
+**Иконка и заголовок выводятся из имени файла.** Расширение выбирает иконку (незнакомое даёт
+общую), а заголовок — это имя без расширения с заменёнными `_` и `-` на пробелы. Отдельных
+входов для них нет.
+
+**Длинное имя обрезается в середине**, чтобы расширение осталось видно: `очень-длинн...pdf`.
+
+**Без входов действий карточка немая** — ни одной кнопки. Она бывает просто вложением, которое
+показывают.

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

@@ -0,0 +1,39 @@
+# `rt-file-drop`
+
+Область приёма файлов перетаскиванием. Оборачивает любое содержимое и показывает подсказку
+поверх него.
+
+```html
+<rt-file-drop accept=".pdf" [zones]="zones" (filesDropped)="attach($event)" (zoneFilesDropped)="attachTo($event)">
+    <app-form />
+</rt-file-drop>
+```
+
+| вход           | тип               | умолчание                  |
+| -------------- | ----------------- | -------------------------- |
+| `disabled`     | `boolean`         | `false`                    |
+| `overlayLabel` | `string`          | `''` → `uiFileDropOverlay` |
+| `zones`        | `readonly Zone[]` | `[]`                       |
+| `accept`       | `string`          | `''`                       |
+
+Выходы: `filesDropped` (`File[]`), `zoneFilesDropped` (`{ zoneId, files }`), `draggingChange`.
+
+## Главное, что нужно знать
+
+**С зонами общее событие сброса не поднимается** — зона обязана быть названа. Без зон, наоборот,
+приходит только `filesDropped`.
+
+**Уход курсора гасит подсказку не сразу** (80 мс). Без задержки рамка мерцала бы при переходе
+между дочерними элементами области.
+
+**Файлы не того типа отсекаются по `accept`**, и пустой после фильтра сброс события не поднимает.
+
+## Края
+
+- Зона выбирается долей от высоты области. Пока высоты нет (первый кадр, скрытая вкладка),
+  выбор детерминирован — первая зона, а не отказ: файл терять нельзя.
+- Отключённая область не показывает подсказку и не принимает файлы.
+
+## Рядом
+
+- [`rt-file-input`](../file-input/CONTEXT.md) — выбор файлов кнопкой.

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`         | `''` → `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`         | `''` → переведённое `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 {