@sberbusiness/triplex-next-mcp-server 1.48.0-beta → 1.50.0-beta

package/bundle/components/Ellipsis.md

@@ -1,9 +1,7 @@
 ---
 component: Ellipsis
-category: Typography
-figma-node: ""
-figma-file: ""
-related: [Typography, Tooltip, Spoiler]
+category: Ellipsis
+related: []
 tokens: []
 stories: stories/Ellipsis/Ellipsis.stories.tsx
 version: "1.0"
@@ -13,191 +11,153 @@ version: "1.0"
 
 ## Назначение
 
-Обрезает многострочный текст с **многоточием** после заданного числа
-строк (`maxLines`). Использует `-webkit-line-clamp` CSS — работает во
-всех современных браузерах (Chromium, Firefox, Safari).
+Контейнер, который обрезает вложенный текст многоточием после заданного числа
+строк. Вся работа делается CSS-свойством `line-clamp` — компонент не измеряет
+текст, не режет строки в JS и не добавляет собственного оформления: рендерит
+один `<div>`, в котором включён многострочный клэмп.
 
-Управление числом строк — через CSS-переменную `--ellipsis-line-clamp`,
-устанавливаемую inline-style'ом. `maxLines=1` включает дополнительный
-класс `.oneLine` с `word-break: break-all` (чтобы длинное слово не
-оставляло пустую строку).
+Используй когда: длина текста не контролируется (название документа, комментарий,
+описание из бэкенда), а место под него в макете фиксировано — одна, две, три
+строки.
 
-Используй когда: у тебя блочный контейнер с текстом, который должен
-помещаться в фиксированное количество строк.
-Не используй когда: нужна интерактивность (развернуть/свернуть) — бери
-`Spoiler`; нужен tooltip с полным текстом — оборачивай в `Tooltip`.
+Не используй когда:
 
----
-
-## Файловая структура
-
-```text
-src/components/Ellipsis/
-├── Ellipsis.tsx                      # forwardRef<HTMLDivElement>
-├── index.ts                          # Barrel
-├── styles/Ellipsis.module.less       # -webkit-line-clamp через CSS-var
-└── __tests__/Ellipsis.test.tsx
-```
-
-Особенности:
-- **`forwardRef`** есть (в отличие от Col/Divider).
-- **`data-tx`** есть.
-- **Единственный проп помимо HTML attributes** — `maxLines`.
-- **Тесты** покрывают базовое поведение.
+- блоку нужны собственные паддинги: обрезка построена на `display: -webkit-box`,
+  вертикальные отступы попадают внутрь обрезаемой области и «съедают» строку.
+  Отступы задаёт обёртка вокруг `Ellipsis`, а не он сам;
+- нужен раскрывающийся текст («показать полностью»): `Ellipsis` не имеет
+  состояния и кнопки — это `Spoiler` или своя связка с `ExpandAnimation`;
+- нужна обрезка ровно по ширине одной строки без многострочной логики: обычного
+  `text-overflow: ellipsis` на своём элементе достаточно, отдельный компонент
+  здесь избыточен;
+- полный текст обязан оставаться видимым — обрезка визуальная и необратимая,
+  пользователь не может её раскрыть.
 
 ---
 
 ## Варианты и props
 
-### `IEllipsisProps extends React.HTMLAttributes<HTMLDivElement>`
-
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `maxLines` | `number` | Да | Максимум строк. После `maxLines`-й строки — многоточие. |
-| `children` | `ReactNode` | — | Текст или inline-элементы. |
-| `className` | `string` | — | Через `clsx`. |
-| `...HTMLDivAttributes` | — | — | Стандартные. |
-
-**Нет дефолтного `maxLines`** — обязательный проп. Если передать 0
-или отрицательное — получишь пустой контейнер (браузер сочтёт 0-строк).
-
----
-
-## Ключевые особенности реализации
-
-### `--ellipsis-line-clamp` CSS-переменная
-
-```tsx
-style={{ "--ellipsis-line-clamp": maxLines } as React.CSSProperties}
-```
+`IEllipsisProps` расширяет `React.HTMLAttributes<HTMLDivElement>` — `...rest`,
+`className` и `style` уходят на корневой `<div>`.
 
-```less
-.ellipsisLineClamp {
-    --ellipsis-line-clamp: 1;
-    -webkit-line-clamp: var(--ellipsis-line-clamp);
-    line-clamp: var(--ellipsis-line-clamp);
-}
-```
+### Обязательные props
 
-**Почему через var, не напрямую inline `WebkitLineClamp`:** чтобы дать
-потребителю возможность переопределить через CSS-scope
-(`.my-class { --ellipsis-line-clamp: 5; }`). Inline-style всегда
-побеждает media-query; переменная может быть перезаписана по
-breakpoint'у.
+| Prop | Тип | Описание |
+|---|---|---|
+| `maxLines` | `number` | Количество строк, после которых текст сворачивается в многоточие. Осмысленны только целые значения ≥ 1: компонент значение не валидирует и передаёт его в CSS как есть |
 
-**TypeScript-каст `as React.CSSProperties`** — CSSProperties не
-допускает custom properties без кастинга. Стандартный приём.
+### Опциональные props
 
-**Fallback `--ellipsis-line-clamp: 1;`** в базовом классе — защита
-если по каким-то причинам inline var не подхватился.
-
-### `-webkit-line-clamp` требует специальной связки
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Обрезаемое содержимое. Рассчитано на текст; блочная разметка внутри `-webkit-box` ведёт себя непредсказуемо |
+| `className` | `string` | — | Мерджится с собственными классами корневого `<div>` через `clsx` |
+| `style` | `React.CSSProperties` | — | Мерджится с runtime-переменной клэмпа: собственные стили потребителя применяются, переменную они не затирают |
 
-```less
-display: -webkit-box;
--webkit-line-clamp: var(--ellipsis-line-clamp);
--webkit-box-orient: vertical;
-overflow: hidden;
-```
+### Что делает `maxLines` кроме числа строк
 
-**Все четыре свойства обязательны.** Без `display: -webkit-box` +
-`-webkit-box-orient: vertical` — `-webkit-line-clamp` игнорируется.
-Без `overflow: hidden` — многоточия не будет.
+Значение уходит в runtime CSS-переменную (см. «Дизайн-токены») и дополнительно
+переключает режим переноса:
 
-**`line-clamp` (без `-webkit-`)** — стандартное свойство, добавлено
-для будущей совместимости. На данный момент все браузеры всё ещё
-используют vendor-префикс, но standard работает в свежих версиях.
+| `maxLines` | Класс | `word-break` | Зачем |
+|---|---|---|---|
+| `1` | `ellipsisLineClamp` + `oneLine` | `break-all` | Единственное длинное слово без пробелов должно обрезаться посередине, а не уезжать за границы |
+| `> 1` | `ellipsisLineClamp` | `break-word` | Обычный перенос по словам, слово рвётся только если целиком не влезает в строку |
 
-### `white-space: normal` (не nowrap)
+---
 
-```less
-white-space: normal;
-```
+## Дизайн-токены
 
-**Важно:** стандартное `white-space: normal` гарантирует, что текст
-может переноситься на новые строки. Без этого `-webkit-line-clamp`
-не сработает — текст просто обрежется справа.
+Собственных дизайн-токенов у компонента нет: `Ellipsis.module.less` задаёт только
+раскладку и правила переноса, цвет и типографика наследуются от родителя.
 
-### `word-break: break-word` vs `break-all` для `maxLines=1`
+Единственная CSS-переменная — runtime-переменная числа строк, которую компонент
+выставляет сам через `style`:
 
-```less
-word-break: break-word;  // default — разрывает только по слову/пробелу
-&.oneLine {
-    word-break: break-all;  // разрывает посреди слова
-}
+```text
+--triplex-next-runtime-Ellipsis-Root_LineClamp
 ```
 
-**Для `maxLines=1`** — `break-all`. Причина: при одной строке,
-если слишком длинное слово, `break-word` оставит **пустую строку**
-перед словом (оно перенесётся целиком на следующую, но её нет).
-`break-all` гарантирует, что хоть часть слова влезет в одну строку,
-а остальное обрежется многоточием.
-
-Для `maxLines > 1` — `break-word` — красивее (слова не разрываются).
-
-### Компонент — `<div>`, не `<p>`
-
-Не рендерит semantic `<p>` или `<span>`. Потребитель может обернуть
-любой текст. Если нужна семантика — использовать `as` через прокидывание
-(не реализовано) или выбрать `Typography.Text` + обернуть в Ellipsis.
+Это не дизайн-токен: она не входит в `src/components/DesignTokens`, не
+переопределяется через `ThemeProvider` и существует только потому, что
+`line-clamp` нельзя выразить фиксированным набором классов для произвольного
+числа строк. В стилях у неё есть fallback `1` — на случай, если разметка
+отрендерена без inline-стиля.
 
 ---
 
 ## Инварианты
 
-- **`maxLines` — обязательный проп**, без дефолта.
-- **Все 4 CSS-свойства** (`display`, `-webkit-line-clamp`, `-webkit-box-orient`,
-  `overflow: hidden`) — обязательны. Не удалять по отдельности.
-- **`--ellipsis-line-clamp` CSS-переменная** — источник значения. Inline
-  style задаёт, LESS читает. Не хардкодить `WebkitLineClamp`.
-- **`white-space: normal`** — обязателен. Не менять на `nowrap`.
-- **`word-break: break-all` только для `maxLines=1`** — класс `.oneLine`
-  добавляется именно при `=== 1`. Не применять для многострочных.
-- **`forwardRef`** — есть.
-- **`data-tx`** — есть, не удалять.
-- **Рендерит `<div>`** — не `<p>`/`<span>`, семантика на потребителе.
+- **`forwardRef` на компоненте — не убирать.** Ref идёт на корневой `<div>` —
+  тот же элемент, что получает `className`, `style` и `...rest`.
+- **Корневой DOM — один `<div>`** с `data-tx` (версия пакета). Тег не
+  настраивается, дополнительных обёрток внутри нет.
+- **Публичные экспорты barrel** (`src/components/Ellipsis/index.ts`): `Ellipsis`,
+  `IEllipsisProps`. Переименование — breaking change.
+- **`displayName = "Ellipsis"`.**
+- **`maxLines` обязателен и остаётся `number`.** Значение по умолчанию не
+  вводится намеренно: тихая обрезка на «каком-то» числе строк хуже, чем явное
+  требование его указать.
+- **Связка CSS-свойств `display: -webkit-box` + `-webkit-box-orient: vertical` +
+  `overflow: hidden` — неразрывная.** Клэмп работает только когда выставлены все
+  три. Переопределение `display` снаружи (через `className` или `style`) отключает
+  обрезку целиком.
+- **`padding: 0` в корневом классе — часть контракта**, а не косметика:
+  вертикальные паддинги искажают количество видимых строк. Отступы задаёт
+  обёртка.
+- **Runtime-переменная `--triplex-next-runtime-Ellipsis-Root_LineClamp`**
+  объявляется в `Ellipsis.tsx` и читается в `Ellipsis.module.less`. Имя следует
+  паттерну `docs/ai/codestyle.md`. Публичным API она не является и через
+  `ThemeProvider` не переопределяется, но видна в inline-стиле корневого
+  элемента, поэтому её имя меняется в обоих файлах разом.
+- **Потребительский `style` мерджится, а не заменяется.** Порядок
+  `{...style, "--...": maxLines}` гарантирует, что `maxLines` не теряется при
+  передаче своих стилей.
+- **CSS-классы `ellipsisLineClamp` и `oneLine`** проверяются unit-тестами —
+  переименование требует синхронного обновления тестов.
 
 ---
 
 ## Accessibility
 
-- **Screen reader получает полный текст** — только `overflow: hidden`
-  визуально, но DOM-текст доступен полностью. Screen reader читает всё.
-- **Если нужен alt/full-text на hover** — оборачивать в `Tooltip` с
-  полным текстом.
-- **Tab-навигация** — div не focusable по умолчанию. Если дети
-  interactive — они доступны обычно.
-- **Нет `title`-атрибута** — Ellipsis не проставляет. Потребитель
-  может передать через `...rest`.
-
----
-
-## Дизайн-токены
-
-**Нет собственных.** Чисто CSS-техника обрезания.
+- Компонент презентационный: своей роли, ARIA-атрибутов, фокуса и клавиатурных
+  обработчиков у него нет. Корневой `<div>` не участвует в порядке обхода по
+  `Tab`.
+- **Обрезка чисто визуальная.** Текст целиком остаётся в DOM и в дереве
+  доступности, поэтому скринридер прочитает его полностью, а поиск по странице
+  найдёт скрытую часть. Для пользователя со зрением текст при этом потерян.
+- Если полный текст важен, потребитель отвечает за его доступность сам:
+  `Tooltip` рядом, `title` на элементе через `...rest` или ссылка на полную
+  версию. Компонент ничего такого не добавляет — библиотека мультиязычная и
+  текстов не хардкодит.
+- `aria-*` и `title` пробрасываются на корневой `<div>` через `...rest`.
 
 ---
 
 ## Связанные компоненты
 
-- `Typography.Text`/`Title` — типичные child'ы (задают шрифт/цвет).
-- `Tooltip` — частая обёртка для показа полного текста при hover'е.
-- `Spoiler` — альтернатива, когда нужна возможность "раскрыть"
-  обрезанный текст.
+Собственных связей-контрактов у компонента нет: он ничего не рендерит внутри
+себя, ни от кого не наследует props и не входит ни в какое семейство — поэтому
+`related` пуст. Полезные соседи при вёрстке:
+
+- `Tooltip` — типичная пара: обрезанный текст плюс подсказка с полным значением
+  по наведению. Связи в коде нет, связку собирает потребитель.
+- `Spoiler` — если текст нужно не обрезать, а сворачивать с возможностью
+  раскрыть.
+- `Text`, `Body` — типографика обрезаемого текста: `Ellipsis` цвет и размер
+  шрифта не задаёт, они наследуются от родителя.
 
 ---
 
 ## Stories
 
-`stories/Ellipsis/Ellipsis.stories.tsx`
-Примеры: `stories/Ellipsis/examples/`
+Основные истории: `stories/Ellipsis/Ellipsis.stories.tsx`
+Файлы примеров: `stories/Ellipsis/examples/`
 
-Типовые stories:
-- `Default` — 1 строка
-- `MultipleLines` — 2, 3, 5 строк
-- `LongWord` — демонстрация `break-all` на одной строке
-- `WithTooltip` — комбинация с Tooltip для показа полного текста
-- `Playground` — интерактив
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `maxLines` на длинном тексте |
+| `Default` | `DefaultExample.tsx` | Обрезка длинного абзаца до двух строк |
 
 ---
 
@@ -205,4 +165,28 @@ word-break: break-word;  // default — разрывает только по с
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-30 | Создан документ (TRI-36). Зафиксированы: обязательность `maxLines` без дефолта, связка `display: -webkit-box` + `-webkit-box-orient` + `overflow: hidden`, запрет паддингов, переключение `word-break` на `maxLines === 1`, мердж потребительского `style` с runtime-переменной `--triplex-next-runtime-Ellipsis-Root_LineClamp` и визуальный (не семантический) характер обрезки |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Ellipsis/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { Ellipsis } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <Ellipsis maxLines={2}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
+        magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+        consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+        pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
+        laborum.
+    </Ellipsis>
+);
+```
+

package/bundle/components/FooterPage.md

@@ -1,7 +1,7 @@
 ---
 component: FooterPage
 category: Page
-related: [Page, HeaderPage, BodyPage, Footer, Island, LightBox]
+related: [Page, HeaderPage, BodyPage, Footer, Island]
 tokens:
   - FooterPage.StickyShadow
 stories: stories/Page/FooterPage/FooterPage.stories.tsx
@@ -115,9 +115,11 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-28 | Токен `FooterPage.StickyShadow` ссылается на `Shadow.05` (светлая) и `DarkShadow.05` (тёмная) вместо литералов: `0 -2px 9px` с прозрачностью 0.15 (светлая) и 0.5 (тёмная). |
 | 2026-09-16 | Добавлен отступ `padding-bottom: 8px` для футера с `type={EFooterPageType.SECOND}`. |
 | 2026-08-06 | Sticky-позиционирование доступно вне `LightBox` при ширине viewport от 992px и отключено при высоте viewport не больше 800px. |
 | 2026-06-19 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`LightBox`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/FormField.md

@@ -1,7 +1,7 @@
 ---
 component: FormField
 category: FormField
-related: [FormFieldLabel, FormFieldInput, FormFieldTextarea, FormFieldTarget, FormFieldMaskedInput, FormFieldPrefix, FormFieldPostfix, FormFieldClear, FormFieldDescription, FormFieldCounter, FormGroup, TextField, TextareaField, MaskedField, SelectField, SuggestField, DateField]
+related: [FormGroup, TextField, TextareaField, MaskedField, SelectField, SuggestField, DateField]
 tokens:
   - FormField.Background_Default
   - FormField.Background_Hover
@@ -175,6 +175,7 @@ FormField.Target_PlaceholderColor_Default
 | 2026-09-16 | Исправлено: `FormFieldInput` и `FormFieldTextarea` очищают `targetId` при размонтировании — иначе после замены элемента ввода на `FormFieldTarget` лейбл сохранял `htmlFor` с `id` удалённого элемента. |
 | 2026-09-17 | Ломающее изменение: `disabled` убран из `IFormFieldTextareaProps` через `Omit` — так же, как он уже был убран у `FormFieldInput` и `FormFieldMaskedInput`. Поведение не менялось (статус перетирал переданное значение и раньше), но передача `disabled` в props теперь ошибка компиляции. Правка по ревью PR #629, зафиксирована в release notes 1.47.0 |
 | 2026-09-23 | Исправлено: при смене `status` на `EFormFieldStatus.DISABLED`, пока вложенный элемент ввода в фокусе, `FormField` теперь явно сбрасывает состояние `focused` в `useLayoutEffect`. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`FormFieldLabel`, `FormFieldInput`, `FormFieldTextarea`, `FormFieldTarget`, `FormFieldMaskedInput`, `FormFieldPrefix`, `FormFieldPostfix`, `FormFieldClear`, `FormFieldDescription`, `FormFieldCounter`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/Gap.md

@@ -1,7 +1,7 @@
 ---
 component: Gap
 category: Layout
-related: [Divider, Col, Row]
+related: [Col, Row]
 tokens: []
 stories: stories/Gap/Gap.stories.tsx
 version: "1.0"

package/bundle/components/Header.md

@@ -194,6 +194,7 @@ Playground не создаётся — у компонента нет настр
 
 | Дата | Изменение |
 |---|---|
+| 2026-10-01 | `Header.Title.Controls` в адаптиве (`max-width: @screen-sm-max`): вместо отрицательного `margin-left` контейнера и `margin-left/top: 16px` у кнопок используется `display: flex; flex-wrap: wrap; gap: 16px 12px` и `margin-top: 16px` у контейнера. Прямым потомкам `button` и `[class*="buttonDropdown"]` собственные `margin` сбрасываются через `!important` (иначе их перебивают правила отступа между соседними кнопками, специфичность 0,3,0), поэтому пользовательские `margin` на них в адаптиве не действуют. Остальные прямые потомки участвуют во flex-раскладке (`align-items: center`). Десктопные стили не менялись. |
 | 2026-08-28 | Создан документ. AI-рефакторинг (JSDoc на `children` и `withoutPaddings`, выровнен порядок аргументов `clsx`, удалён мёртвый CSS-селектор `.headerLink` и пустое правило `.headerTitleContent`), unit-тесты на все одиннадцать компонентов, stories по modern pattern. |
 
 ---

package/bundle/components/HeaderPage.md

@@ -1,7 +1,7 @@
 ---
 component: HeaderPage
 category: Page
-related: [Page, BodyPage, FooterPage, Header, Island, LightBox]
+related: [Page, BodyPage, FooterPage, Header, Island]
 tokens:
   - HeaderPage.StickyShadow
 stories: stories/Page/HeaderPage/HeaderPage.stories.tsx
@@ -118,8 +118,10 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-28 | Токен `HeaderPage.StickyShadow` ссылается на `Shadow.04` (светлая) и `DarkShadow.04` (тёмная) вместо литералов: `0 2px 9px` с прозрачностью 0.15 (светлая) и 0.5 (тёмная). |
 | 2026-08-06 | Sticky-позиционирование доступно вне `LightBox` при ширине viewport от 992px и отключено при высоте viewport не больше 800px. |
 | 2026-06-23 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`LightBox`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/HelpBox.md

@@ -1,7 +1,7 @@
 ---
 component: HelpBox
 category: HelpBox
-related: [Tooltip, ButtonIcon, MobileView, FocusTrap]
+related: [Tooltip, ButtonIcon, MobileView]
 tokens: []
 stories: stories/HelpBox/HelpBox.stories.tsx
 version: "1.0"
@@ -119,6 +119,7 @@ version: "1.0"
 | 2026-07-08 | Актуализирована колонка `Example file`: имена файлов примеров приведены к фактическим (без постфикса `Example`). |
 | 2026-09-08 | AI-рефакторинг: `useId` заменён на `uniqueId` (совместимость с React 17), callback-`ref` стабилизирован через `useCallback`, убраны `!` и `as`-каст в работе с `ref`, `TooltipMobileHeader` берётся из composition-API `Tooltip.MobileHeader`, `paletteIndex` иконки вынесен в константу. Добавлены unit-тесты (25 кейсов, включая мобильную версию). |
 | 2026-09-10 | Ловушка фокуса больше не активируется при открытии подсказки наведением мыши (`needFocusTrap`): фокус остаётся в элементе, с которым работает пользователь. Добавлены unit-тесты на hover- и клавиатурный сценарии. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`FocusTrap`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/IconWrapper.md

@@ -112,15 +112,19 @@ CSS-модуль `styles/IconWrapper.module.less` содержит только
   сделать кликабельную иконку.
 - `Link` (`src/components/Link/Link.tsx`) — оборачивает содержимое ссылки в
   `IconWrapper displayContents`, чтобы иконка внутри ссылки красилась вместе с текстом.
-- `Button` (`src/components/Button/Button.tsx`) — оборачивает содержимое кнопки в
-  `IconWrapper` с кастомным `className` и прокидывает `disabled` / `active`. Единственный
-  в `src/**` случай передачи собственного `className` в IconWrapper.
 - `Chip`, `ChipSort`, `SegmentedControlSegment`, `StepperStep`, `ListItemControlsButton`,
   `SelectExtendedFieldTarget` — используют IconWrapper для синхронизации цвета иконки
   с состоянием элемента.
-- `CollapsibleTreeNodeHeader` (`src/components/CollapsibleTree/components/`) — не использует
-  IconWrapper, но ставит те же глобальные классы напрямую на `<button>`; при изменении логики
-  классов держи оба места синхронными.
+- `Button` (`src/components/Button/Button.tsx`), `CollapsibleTreeNodeHeader`
+  (`src/components/CollapsibleTree/components/`) — **не используют** IconWrapper, ставят те
+  же глобальные классы (`hoverable` / `active` / `disabled`) напрямую на корневой `<button>`;
+  при изменении логики классов держи все места синхронными. `Button` явно переходил на
+  `IconWrapper displayContents` и откатился: обёртка добавляла DOM-узел вокруг `<button>`, из-за
+  чего два соседних `Button` переставали быть смежными DOM-siblings и ломался CSS-отступ между
+  ними (`.button + .button` в `Button.module.less`), плюс это меняло корневой DOM-элемент,
+  который внешние потребители могли таргетить напрямую (`>`- и sibling-селекторы). Для
+  `ButtonIcon`/`SegmentedControlSegment` того же риска нет — у них нет CSS, зависящего от
+  смежности соседних экземпляров.
 
 ---
 

package/bundle/components/ImageGallery.md

@@ -1,7 +1,7 @@
 ---
 component: ImageGallery
 category: ImageGallery
-related: [ImageGalleryExtended, MobileView, LightBox]
+related: [ImageGalleryExtended, MobileView]
 tokens:
   - ImageGallery.Accent_Color
   - ImageGallery.Arrow_Background_Default
@@ -194,6 +194,7 @@ Runtime CSS-переменная высоты крупной картинки
 |---|---|
 | 2026-05-28 | Создан документ |
 | 2026-08-31 | Удалены неиспользуемые токены `Arrow_Background_Disabled` и `Arrow_BorderColor_Disabled`: неактивная стрелка скрывается (`display: none`), красить нечем |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`LightBox`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/ImageGalleryExtended.md

@@ -1,7 +1,7 @@
 ---
 component: ImageGalleryExtended
 category: ImageGalleryExtended
-related: [ImageGallery, MobileView, LightBox]
+related: [ImageGallery, MobileView]
 tokens:
   - ImageGallery.Accent_Color
   - ImageGallery.Arrow_Background_Default
@@ -247,6 +247,7 @@ API (экспортируются из barrel ради композиции, н
 |---|---|
 | 2026-05-28 | Создан документ |
 | 2026-08-31 | Удалены неиспользуемые токены `Arrow_Background_Disabled` и `Arrow_BorderColor_Disabled`: неактивная стрелка скрывается (`display: none`), красить нечем |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`LightBox`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/IslandAccordion.md

@@ -1,7 +1,7 @@
 ---
 component: IslandAccordion
 category: Layout
-related: [Island, IslandWidget, ExpandAnimation, Step, ButtonIcon]
+related: [Island, IslandWidget, Spoiler, ExpandAnimation, Step, ButtonIcon]
 tokens:
   - IslandAccordion.Type1_Header_Background_Hover
   - IslandAccordion.Type2_Header_Background_Hover
@@ -226,6 +226,10 @@ Hover-фон заголовка применяется только к **свё
   пользу, поэтому правки селекторов отступов `Island` ломают аккордеон молча.
 - `IslandWidget` — виджет на `Island`, который сворачивается в адаптиве, а не по клику. Свои
   Header / Body / Footer, частями `Island` не пользуется.
+- `Spoiler` — альтернатива уровнем ниже: одна кнопка-ссылка, раскрывающая содержимое на месте.
+  Ни карточки, ни заголовка с номером и статусом, ни удаления, ни группировки нескольких
+  элементов, ни анимации высоты — содержимое переключается мгновенно. Если раскрываемый блок
+  не должен выглядеть самостоятельной секцией, нужен он, а не аккордеон.
 
 ### Контракты по рендеру (в `related`)
 
@@ -271,6 +275,7 @@ Hover-фон заголовка применяется только к **свё
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-28 | В `related` и «Альтернативы» добавлен `Spoiler` — симметрия связи-альтернативы с его AI.md (TRI-81). Правка только документации. |
 | 2026-09-09 | Создан документ. AI-рефакторинг: JSDoc на props, компонентах и контексте; синхронизация `opened` перенесена из `useEffect` в фазу рендера (промежуточный кадр со старым состоянием больше не отрисовывается); автогенерируемые id заголовка и содержимого получили вид `IslandAccordionItem-<n>-header` / `-body`; при `num={0}` со статусом больше не отрисовывается текст «0»; добавлены unit-тесты на `IslandAccordionItem`, контекст, части и публичный контракт `IslandAccordion`. Публичный API не изменён. |
 
 ---

package/bundle/components/KeyDownListener.md

@@ -117,8 +117,8 @@ version: "1.0"
 - `TriggerClickOnKeyDownEvent` (`src/components/Triggers/`) — по нажатию клавиши
   вызывает `click` на элементе из `targetRef`.
 - `SelectExtendedField` — закрывает выпадающий список по `Esc`.
-- `SliderExtendedDot`, `SliderExtendedTrack` — стрелки для перемещения ползунка,
-  слушатели монтируются только когда элемент в фокусе.
+- `SliderExtended` (`SliderExtendedDot`, `SliderExtendedTrack`) — стрелки для перемещения
+  ползунка, слушатели монтируются только когда элемент в фокусе.
 
 ---
 
@@ -149,6 +149,7 @@ version: "1.0"
 | 2026-08-11 | TRI-112: у `ComposedKeyDownListener` появились собственный `ComposedKeyDownListener-ai.md` и набор stories `stories/ComposedKeyDownListener/`; раздел «Связанные компоненты» сокращён до ссылки, story `Example` (демонстрация композитора) перенесена в новый набор. Ограничение на стабильную длину `keyDownListeners` снято — композитор рендерит слушателей соседями к `children`. Набор stories `KeyDownListener` исключён из скриншот-тестов, story `VisualTests` и baseline удалены — визуального интерфейса у компонента нет. Реализация самого `KeyDownListener` не менялась. |
 | 2026-08-04 | По ревью PR #502: интерфейс props `IComposedKeyDownListenerProps` стал экспортируемым — публичная поверхность пакета расширена аддитивно. `ComposedKeyDownListener` добавлен отдельной строкой в `docs/ai/ROADMAP.md`, собственный AI.md вынесен в отдельную задачу. |
 | 2026-08-04 | Создан документ. AI-рефакторинг (TRI-48): JSDoc на props `IKeyDownListenerProps` и `ComposedKeyDownListener`, ветвление в `handleKeyDown` сведено к одной проверке (снят `eslint-disable`), в `ComposedKeyDownListener` убран `as JSX.Element` и добавлен `displayName`, unit-тесты (16 кейсов на оба компонента), stories по modern pattern. Публичный API не менялся; компонент остаётся class-компонентом, `forwardRef` осознанно отсутствует. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): в «Связанных компонентах» потребители `SliderExtendedDot` / `SliderExtendedTrack` названы через адресата `related` — `SliderExtended`. Публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/LightBox.md

@@ -1,7 +1,7 @@
 ---
 component: LightBox
 category: LightBox
-related: [Page, TopOverlay, Portal, FocusTrapExtended, LoaderScreen, Button, ModalWindow]
+related: [Page, TopOverlay, Portal, LoaderScreen, Button, ModalWindow, Overlay]
 tokens:
   - LightBox.Backdrop_Background
   - LightBox.Content_Background
@@ -173,10 +173,15 @@ css-переменную `--lightBox-scroll-width`, которую вычита
 - `LightBoxControls` + `LightBoxClose` / `LightBoxPrev` / `LightBoxNext` (`LightBoxControls/`) — кнопки управления; стрелки построены на общем внутреннем `LightBoxArrow` (не экспортируется)
 - `LightBoxLeftSidebar` / `LightBoxRightSidebar` (`LightBoxSidebars/`) — сайдбары с автоскрытием содержимого по ширине (общий хук `useLightBoxSidebarVisibility`)
 - `LightBoxSideOverlay` (`LightBoxSideOverlay/`) — выезжающая справа панель с собственным focus trap, лоадером и кнопками закрытия CloseDesktop/CloseMobile
+- `FocusTrapExtended` (`src/components/FocusTrapExtended`) — focus trap окна и боковой панели; настраивается через `focusTrapProps` (`IFocusTrapExtendedProps`). Своего AI.md и строки в `docs/ai/ROADMAP.md` не имеет
 - `LightBoxViewManager` (`LightBoxViewManager/`) — внутренний менеджер позиционирования: следит за границами view-manager-ноды, проставляет breakpoint-классы и CSS-переменные
 - `TopOverlay` (`src/components/TopOverlay`) — верхняя панель, реэкспортируется как `LightBox.TopOverlay`
 - `Page` (`src/components/Page`) — рекомендуемая структура содержимого `LightBox.Content`
 - `ModalWindow` — альтернатива для компактных диалогов
+- `Overlay` (`src/components/Overlay`) — механика оверлея, на которой построен `LightBox.SideOverlay`: `ILightBoxSideOverlayProps` берёт `opened` / `onClose` из `IOverlayBaseProps`, подложку рисует `OverlayMask`
+- `Portal` (`src/components/Portal`) — рендер содержимого в отдельный узел вне текущего DOM-поддерева
+- `LoaderScreen` (`src/components/LoaderScreen`) — экран загрузки боковой панели, настраивается через `loaderScreenProps`
+- `Button` (`src/components/Button`) — на нём построены кнопки управления: `LightBox.Controls` (закрытие и стрелки через общий `LightBoxArrow`) и кнопки закрытия `LightBox.SideOverlay`
 
 ---
 
@@ -215,6 +220,7 @@ css-переменную `--lightBox-scroll-width`, которую вычита
 | 2026-07-22 | Багфиксы по ревью PR #474: клавиатурные триггеры контролов целятся в видимую кнопку (стрелки не работали на desktop, Esc — на mobile); таймер-хак блокировки скролла заменён счётчиком смонтированных лайтбоксов; `LightBoxViewManager` снимает классы mount-ноды при размонтировании последнего менеджера |
 | 2026-08-17 | Исправлено: `LightBox.TopOverlay` перекрывался лоадером `LightBox.Content`. У `.loadingContentOverlay` теперь локальный z-index (201) — выше sticky-шапки и футера `Page`, но ниже `TopOverlay` (500); раньше `LoaderScreen` шёл с глобальным `@z-index-loader-screen` (10100) |
 | 2026-08-25 | Исправлено: в состоянии загрузки кнопка закрытия была недоступна для клика — её перекрывал лоадер `LightBox.Content`. Восстановлен модификатор `isLoading` на корневом элементе (терялся при переходе на CSS Modules): контролы поднимаются над лоадером, кнопки вперёд/назад скрываются. Esc в состоянии загрузки сохранён рабочим |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`FocusTrapExtended`); добавлены обратные ссылки (`Overlay`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/List.md

@@ -1,7 +1,7 @@
 ---
 component: List
 category: List
-related: [ListSortable, ListItem, ListEmptyState, ListItemLoading, LoaderScreen]
+related: [ListSortable, ListItem, LoaderScreen]
 tokens: []
 stories: stories/List/List.stories.tsx
 version: "1.0"
@@ -75,6 +75,7 @@ version: "1.0"
 |---|---|
 | 2026-04-29 | Создан документ |
 | 2026-06-17 | `List.module.less`: локальный `z-index: @z-index-step` на `.listLoaderScreen` — исправлено перекрытие `LoaderScreen` поверх `LightBox` / `ModalWindow` |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`ListEmptyState`, `ListItemLoading`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---