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

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`.
+
+## Края
+
+- Пустой набор рисует заглушку с переведённым `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`                                      | `''` → `uiTabInvalid` |
+
+## Главное, что нужно знать
+
+**Вход `activeId` необязателен.** Без него компонент помнит выбор сам — управляемый режим нужен
+только когда вкладка лежит в адресе страницы.
+
+**Идентификатор, которого нет, откатывается на первую доступную вкладку.** То же с отключённой:
+активной она стать не может. Так вкладка из старой ссылки не оставляет пустой экран.
+
+## Клавиатура и доступность
+
+- Стрелки (влево/вправо, а в вертикальной раскладке вверх/вниз) перешагивают отключённые вкладки
+  и заворачиваются по кругу; `Home`/`End` — к первой и последней.
+- В таб-порядке стоит **только активная** вкладка (`tabindex="0"`), остальные достаются стрелками.
+- Панель и вкладка связаны в обе стороны: `aria-controls` ↔ `aria-labelledby`.
+
+## Края
+
+- `hidden` убирает вкладку из шапки целиком; `disabled` оставляет её видимой, но некликабельной.
+- У невалидной вкладки появляется подсказка с текстом `invalidMessage`.
+- Стрелки прокрутки шапки есть в разметке всегда — показывает их модификатор `--visible`,
+  который выставляется по замеру ширины после отрисовки.

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

@@ -0,0 +1,47 @@
+# `rt-tag`
+
+```html
+<rt-tag value="Активен" severity="success" shape="pill" appearance="solid" icon="check" [closable]="true" (closed)="onClosed($event)" />
+```
+
+| вход               | тип                                                                        | умолчание      |
+| ------------------ | -------------------------------------------------------------------------- | -------------- |
+| `value`            | `string`                                                                   | **обязателен** |
+| `severity`         | `'info' \| 'success' \| 'warning' \| 'danger' \| 'secondary' \| 'neutral'` | `'neutral'`    |
+| `shape`            | `'pill' \| 'square'`                                                       | `'pill'`       |
+| `appearance`       | `'solid' \| 'outlined'`                                                    | `'solid'`      |
+| `radius`           | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full' \| null`                         | `null`         |
+| `icon` / `iconEnd` | `IRtIcon.Name \| null`                                                     | `null`         |
+| `closable`         | `boolean`                                                                  | `false`        |
+
+| выход    | тип          |
+| -------- | ------------ |
+| `closed` | `MouseEvent` |
+
+## Главное, что нужно знать
+
+**Крестик не закрывает тег.** `closed` только сообщает о клике — убрать тег из списка обязан
+потребитель. Компонент состояния не держит.
+
+Клик по крестику **не всплывает** (`stopPropagation`): пилюля целиком часто сама кликабельна,
+и без этого одно нажатие срабатывало бы дважды.
+
+## Как этим пользоваться
+
+- `radius` перебивает скругление, заданное формой. Без него класс скругления не выводится
+  вовсе — радиус берётся из `shape`.
+- Палитра дублируется атрибутом `data-severity` — по нему тег находят проверки и внешние стили,
+  не завязываясь на BEM-класс.
+- Подпись крестика для скринридера берётся из словаря кита (`uiRemove`). Без
+  `provideRtKitLabels()` там будет пусто.
+
+## Края
+
+- `value` — обязательный вход: тег без текста не бывает. Иконка без текста — это
+  [`rt-icon-button`](../icon-button/CONTEXT.md), а не тег.
+- Модификаторы выводятся BEM-директивами: `rt-tag--severity--success`, `rt-tag--shape--square`,
+  булев `closable` даёт `rt-tag--closable` без значения.
+
+## Рядом
+
+- [`rt-live-badge`](../live-badge/CONTEXT.md) — пилюля живого счётчика, а не статуса.

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

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

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

@@ -0,0 +1,38 @@
+# `rt-textarea`
+
+```html
+<rt-field label="Комментарий">
+    <rt-textarea resize="vertical" placeholder="Что уточнить" [formControl]="comment" [rows]="5" />
+</rt-field>
+```
+
+Свои входы поверх общих из [`RtFormControlBase`](../form-control/CONTEXT.md):
+
+| вход          | тип                    | умолчание    |
+| ------------- | ---------------------- | ------------ |
+| `placeholder` | `string`               | `''`         |
+| `rows`        | `number \| string`     | `3`          |
+| `resize`      | `'none' \| 'vertical'` | `'vertical'` |
+| `readonly`    | `boolean`              | `false`      |
+
+Значение — `string`.
+
+## Главное, что нужно знать
+
+**Крестик очистки не рисуется.** Вход `clearable` наследуется от общей основы полей, но разметка
+многострочного поля его не использует: в многострочном вводе он нетипичен.
+
+**Два разных «только для чтения»:**
+
+- свой вход `[readonly]` оставляет `<textarea>` на месте и запрещает правку (нативный `readOnly`);
+- режим от вмещающего [`rt-field`](../field/CONTEXT.md) подменяет контрол плоским текстом.
+
+## Края
+
+- `font-family: inherit` прописан явно: без него `<textarea>` падает на моноширинный шрифт
+  браузера.
+- Горизонтальное растягивание не предусмотрено — только `none` и `vertical`.
+
+## Рядом
+
+- [`rt-rich-editor`](../rich-editor/CONTEXT.md) — когда нужна разметка внутри текста.

package/src/lib/components/theme-toggle/CONTEXT.md

@@ -0,0 +1,28 @@
+# `rt-theme-toggle`
+
+Переключатель светлой и тёмной темы.
+
+```html
+<rt-theme-toggle appearance="icon" />
+```
+
+| вход         | тип                  | умолчание |
+| ------------ | -------------------- | --------- |
+| `appearance` | `'icon' \| 'switch'` | `'icon'`  |
+
+Выходов нет.
+
+## Главное, что нужно знать
+
+**Своего состояния у контрола нет — тему держит `ThemeService`.**
+Он пишет `data-theme` на `<html>` и сохраняет выбор в хранилище устройства, поэтому тема
+переживает перезагрузку, а два переключателя на странице всегда согласованы.
+
+**Иконка показывает, куда переключит**, а не текущее состояние: в светлой теме это луна.
+В виде кнопки текущая тёмная тема помечается `aria-pressed="true"`.
+
+## Края
+
+- Подпись берётся из словаря кита (`themeToggleLabel`) и вычисляется один раз при создании.
+- В тестах между случаями надо чистить хранилище: иначе выбор предыдущего теста становится
+  начальным состоянием следующего.

package/src/lib/components/theme-toggle/rt-theme-toggle.component.scss

@@ -1,3 +1,7 @@
-:host {
+/* rt-theme-toggle — ViewEncapsulation.None: правило таргетирует BEM-класс блока.
+   `.rt-theme-toggle` — сам хост: своей разметки блока у компонента нет, внутри
+   только rt-toggle-switch либо rt-icon-button. */
+
+.rt-theme-toggle {
     display: inline-flex;
 }

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

@@ -0,0 +1,42 @@
+# `rt-thread-list`
+
+Список переписок/заявок с поиском, фильтрами и бесконечной прокруткой. Строку рисует шаблон
+потребителя.
+
+```html
+<rt-thread-list
+    [rows]="rows()"
+    [activeId]="activeId()"
+    [loading]="loading()"
+    [hasMore]="hasMore()"
+    (selectRow)="open($event)"
+    (openInNewTab)="openInTab($event)"
+    (searchChange)="search($event)"
+    (loadMore)="next()">
+    <ng-template rtThreadListRow let-row>…</ng-template>
+    <ng-template rtThreadListFilters>…</ng-template>
+</rt-thread-list>
+```
+
+Входы: `rows`, `activeId`, `searchPlaceholder`, `emptyText`, `loading`, `fetching`, `hasMore`,
+`filtersActive`. Выходы: `selectRow`, `openInNewTab`, `searchChange`, `loadMore`.
+
+Строка обязана иметь `id`, `hasUnread` и (необязательно) `overdue` — это всё, что список о ней знает.
+
+## Главное, что нужно знать
+
+**Ctrl/Cmd+клик просит открыть в новой вкладке, а не выбирает строку.** Список — это навигация,
+и привычка «Ctrl+клик открывает рядом» должна работать.
+
+**`loading` подменяет строки заглушками только при пустом списке.** Загрузка поверх уже
+показанных строк их не трогает — иначе список мигал бы при каждой смене фильтра.
+
+**Поиск отдаёт значение с задержкой** и без повторов (`searchDebounce` + `distinctUntilChanged`),
+уже обрезанное по краям.
+
+## Края
+
+- Якорь догрузки (`rtInfiniteScroll`) появляется только при `hasMore`.
+- Кнопка фильтров рисуется, только если объявлен шаблон `[rtThreadListFilters]`;
+  `filtersActive` рисует на ней точку.
+- Собственное поле поиска можно заменить шаблоном `[rtThreadListSearch]`.

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

@@ -0,0 +1,33 @@
+# `rt-timeline`
+
+```html
+<rt-timeline
+    [steps]="[
+    { label: 'Заявка создана', meta: '12 марта, 10:00', actor: 'Иванов', status: 'complete' },
+    { label: 'На проверке', meta: '12 марта, 12:30', status: 'current' },
+    { label: 'Решение', status: 'pending' },
+]" />
+```
+
+| вход    | тип                                           | умолчание |
+| ------- | --------------------------------------------- | --------- |
+| `steps` | `readonly { label, meta?, actor?, status }[]` | `[]`      |
+
+`status` — `'complete' \| 'current' \| 'pending'`. Выходов нет: лента только показывает.
+
+## Главное, что нужно знать
+
+**Порядок шагов — часть смысла**, поэтому лента рисуется тегом `<ol>`, а не набором блоков.
+
+Соединительная линия рисуется **между** пунктами и не рисуется после последнего: хвост под
+последним шагом читался бы как «продолжение есть».
+
+## Края
+
+- `meta` и `actor` необязательны и рисуются по отдельности: исполнитель без времени допустим.
+- Состояние дублируется атрибутом `data-status` — по нему шаг находят проверки.
+- Пустой набор рисует пустой `<ol>`, а не заглушку: текст «событий нет» подставляет потребитель.
+
+## Рядом
+
+- [`rt-stepper`](../stepper/CONTEXT.md) — линейный прогресс по шагам, а не журнал событий.

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

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

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

@@ -0,0 +1,53 @@
+# `rt-toaster` + `rt-toast`
+
+Стопка всплывающих уведомлений. В разметку ставится **один** `rt-toaster` — обычно в корне
+приложения; отдельные `rt-toast` он создаёт сам.
+
+```html
+<!-- один раз на приложение -->
+<rt-toaster position="bottom-right" [duration]="4000" [visibleToasts]="3" />
+```
+
+```typescript
+readonly #notifications: NotificationBus = inject(NotificationBus);
+
+this.#notifications.success('Сохранено');
+this.#notifications.error('Не удалось сохранить', 'danger', {
+    description: 'Проверьте соединение',
+    action: { label: 'Повторить', handler: (): void => this.retry() },
+});
+```
+
+| вход `rt-toaster` | тип                                                                                               | умолчание        |
+| ----------------- | ------------------------------------------------------------------------------------------------- | ---------------- |
+| `position`        | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` |
+| `duration`        | `number \| string` (мс)                                                                           | `4000`           |
+| `visibleToasts`   | `number \| string`                                                                                | `3`              |
+| `expand`          | `boolean`                                                                                         | `false`          |
+
+## Главное, что нужно знать
+
+**Тосты показываются не входом, а шиной.** Стопка подписана на
+`NotificationBus` и других способов показать тост
+нет. Шина — `providedIn: 'root'`, поэтому её достаточно инжектировать где угодно.
+
+Четыре метода шины задают палитру и иконку: `success` → `check-circle`, `info` → `info-circle`,
+`warning` → `exclamation-circle`, `error` → `times-circle`.
+
+## Как этим пользоваться
+
+- Новый тост встаёт **первым** — стопка растёт сверху.
+- Наведение на стопку разворачивает её и приостанавливает исчезновение; нажатая кнопка мыши
+  удерживает развёрнутое состояние до отпускания.
+- `action` и `secondaryAction` рисуются кнопками внутри тоста и зовут переданные обработчики.
+- `meta` — приписка над сообщением (номер заявки), `description` — вторая строка под ним.
+- Положение раскладывается на два модификатора: `rt-toaster--y--bottom` и `rt-toaster--x--right`.
+
+## Доступность
+
+Стопка — `role="region"` с переведённой подписью, каждый тост — `role="status"` с
+`aria-atomic="true"`: скринридер читает уведомление целиком, а не по изменившимся кускам.
+
+## Рядом
+
+- [`rt-message`](../message/CONTEXT.md) — постоянное сообщение внутри страницы, а не всплывающее.

package/src/lib/components/toggle-button-group/CONTEXT.md

@@ -0,0 +1,38 @@
+# `rt-toggle-button-group<T>`
+
+Группа сегментированных кнопок: один выбранный вариант из нескольких.
+
+```html
+<rt-toggle-button-group
+    ariaLabel="Период"
+    [options]="[{ value: 'day', label: 'День' }, { value: 'week', label: 'Неделя' }]"
+    [value]="period()"
+    (valueChange)="period.set($event)" />
+```
+
+| вход                     | тип                                              | умолчание      |
+| ------------------------ | ------------------------------------------------ | -------------- |
+| `options`                | `ReadonlyArray<{ value, label, icon?, title? }>` | **обязателен** |
+| `value`                  | `T \| undefined`                                 | `undefined`    |
+| `ariaLabel`              | `string \| null`                                 | `null`         |
+| `size`                   | `'sm' \| 'md' \| 'lg'`                           | `'sm'`         |
+| `disabled` / `fullWidth` | `boolean`                                        | `false`        |
+
+Выход: `valueChange`.
+
+## Главное, что нужно знать
+
+**Группа не держит состояния.** Нажатие только просит сменить значение; подсветка сдвинется,
+когда потребитель вернёт новое `value`. Повторное нажатие по выбранному тоже поднимает событие —
+снимать выбор группа не умеет.
+
+## Края
+
+- Крайние кнопки помечены модификаторами `--first` / `--last`: по ним скругляются углы группы.
+- `title` варианта превращается во всплывающую подсказку.
+- Размер иконки выводится из размера группы: `sm` → 12px, `md`/`lg` → 16px.
+
+## Рядом
+
+- [`rt-filter-control`](../filter-control/CONTEXT.md) — та же группа, но с автоматическим
+  переключением на список на узком экране.

package/src/lib/components/toggle-button-group/rt-toggle-button-group.component.scss

@@ -1,10 +1,13 @@
-/* rt-toggle-button-group — segmented control.
-   ViewEncapsulation = default (Emulated) → стили обёрнуты в :host { ... }.
+/* rt-toggle-button-group — segmented control. ViewEncapsulation.None.
+   Хост адресуется по имени элемента, а не по классу блока: класс
+   `.rt-toggle-button-group` висит и на `<rt-toggle-button-group>`, и на корне
+   шаблона, поэтому правила блока вложены в хост — так они достаются только
+   корню шаблона.
    Размеры — три тира sm/md/lg, общая высота совпадает с rt-button
    (sm 30 / md 40 / lg 50px).
    Цвета — только семантические --rt-* токены. */
 
-:host {
+rt-toggle-button-group {
     display: inline-flex;
 
     /* Локальные overridable custom properties — позволяют потребителю
@@ -114,7 +117,7 @@
 }
 
 /* full-width: группа растягивается на контейнер, опции делят ширину поровну. */
-:host(.rt-toggle-button-group--full-width) {
+rt-toggle-button-group.rt-toggle-button-group--full-width {
     display: flex;
     width: 100%;
 
@@ -131,8 +134,10 @@
 
 /* Dark theme: `--rt-color-bg-surface-subtle` совпадает с `--rt-color-bg-surface`
    в палитре (см. styles/_theme-dark.scss), поэтому track теряет контраст с
-   активным сегментом. Локально перекрашиваем track в более тёмный neutral. */
-:host-context(:root[data-theme='dark']),
-:host-context(html.rt-theme-dark) {
+   активным сегментом. Локально перекрашиваем track в более тёмный neutral.
+   Раньше правило было записано через `:host-context`, который под None не
+   совпадает ни с чем: тему задаёт предок, им же и адресуемся. */
+:root[data-theme='dark'] rt-toggle-button-group,
+html.rt-theme-dark rt-toggle-button-group {
     --rt-toggle-button-group-track-bg: var(--rt-neutral-900);
 }

package/src/lib/components/toggle-switch/CONTEXT.md

@@ -0,0 +1,35 @@
+# `rt-toggle-switch`
+
+```html
+<rt-toggle-switch ariaLabel="Тёмная тема" size="md" iconOff="ico-sun" iconOn="ico-moon" [formControl]="darkTheme" />
+```
+
+| вход                 | тип                    | умолчание |
+| -------------------- | ---------------------- | --------- |
+| `inputId`            | `string \| null`       | `null`    |
+| `ariaLabel`          | `string \| null`       | `null`    |
+| `size`               | `'sm' \| 'md' \| 'lg'` | `'sm'`    |
+| `iconOff` / `iconOn` | `IRtIcon.Name \| null` | `null`    |
+| `disabled`           | `boolean`              | `false`   |
+
+Значение — `boolean` через `ControlValueAccessor`. Своей подписи на экране нет.
+
+## Главное, что нужно знать
+
+**`role="switch"`, а не `checkbox`.** Скринридер произносит «switch off/on» вместо «checkbox
+unchecked» — для тумблера это точнее. Своего текста у контрола нет, поэтому подпись задаётся
+входом `ariaLabel` или внешним `<label for>` через `inputId`.
+
+## Как этим пользоваться
+
+- Умолчание размера — `sm`: он совпадает по высоте с плотными контролами формы, где тумблер
+  стоит в одном ряду с текстом.
+- Достаточно одной из двух иконок, чтобы включился режим с иконками
+  (`rt-toggle-switch--with-icons`). Бегунок непрозрачен и наезжает на иконку текущего состояния,
+  так что видна всегда иконка того состояния, куда переключится контрол.
+- Отключение приходит двумя путями — вход и `FormControl.disable()` — и оба пишут в один сигнал.
+
+## Рядом
+
+- [`rt-checkbox`](../checkbox/CONTEXT.md) — для «отмечено», а не «включено».
+- [`rt-theme-toggle`](../theme-toggle/CONTEXT.md) — готовый переключатель темы поверх этого.

package/src/lib/components/toggle-switch/rt-toggle-switch.component.scss

@@ -1,8 +1,13 @@
-:host {
+/* rt-toggle-switch — переключатель в common/ui. ViewEncapsulation.None.
+   Хост адресуется по имени элемента, а не по классу блока: класс `.rt-toggle-switch` висит
+   и на `<rt-toggle-switch>`, и на корне шаблона, поэтому правила блока вложены в хост —
+   так они достаются только корню шаблона. */
+
+rt-toggle-switch {
     display: inline-flex;
 }
 
-.rt-toggle-switch {
+rt-toggle-switch .rt-toggle-switch {
     /* Геометрия размера. База — `sm`; модификаторы перекрывают только числа,
        правила ниже к размерам не привязаны. `thumb-travel` держим явным
        числом, а не calc из ширины: каждое значение сверяется с макетом. */
@@ -58,7 +63,11 @@
             box-shadow var(--rt-duration-fast) ease;
     }
 
-    &--on &__track {
+    /* Элемент адресуется классом, а не вторым `&`: родитель здесь составной
+       (`rt-toggle-switch .rt-toggle-switch`), и второй `&` развернулся бы в него целиком —
+       то есть в селектор, требующий вложенного переключателя. Включённое состояние
+       из-за этого не применялось: трек оставался серым, бегунок — слева. */
+    &--on .rt-toggle-switch__track {
         background: var(--rt-toggle-color-track-on);
         box-shadow: none;
     }
@@ -92,7 +101,7 @@
         transition: transform var(--rt-duration-fast) ease;
     }
 
-    &--on &__thumb {
+    &--on .rt-toggle-switch__thumb {
         transform: translateX(var(--rt-toggle-thumb-travel));
     }
 }