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

package/bundle/components/CheckboxTree.md

@@ -1,9 +1,7 @@
 ---
 component: CheckboxTree
 category: Inputs
-figma-node: ""
-figma-file: ""
-related: [CheckboxTreeExtended, Checkbox, CheckboxYGroup, CheckboxXGroup]
+related: [CheckboxTreeExtended, Checkbox]
 tokens: []
 stories: stories/CheckboxTree/CheckboxTree.stories.tsx
 version: "1.0"
@@ -13,263 +11,206 @@ version: "1.0"
 
 ## Назначение
 
-"Готовый" компонент дерева чекбоксов с автоматической логикой
-checked/bulk-состояний: при клике на родителя все потомки чекаются/
-разчекаются; при частичном выборе потомков родитель получает `bulk: true`
-(состояние "indeterminate").
+Дерево чекбоксов, которое строится из массива данных и само связывает состояние
+родителей и потомков. Обёртка над `CheckboxTreeExtended`: разметку узлов
+компонент формирует сам, потребитель передаёт только описание дерева
+(`ICheckboxTreeCheckboxData[]`) и получает в `onChange` новый массив с
+пересчитанными флагами `checked` и `bulk`.
 
-Является **тонкой data-driven обёрткой** над `CheckboxTreeExtended`:
-потребитель передаёт плоское описание дерева (`ICheckboxTreeCheckboxData[]`),
-компонент сам рендерит `CheckboxTreeExtended.Node` + `.Checkbox`, управляет
-состоянием и отдаёт обновлённый массив в `onChange`.
+Каскадная логика — единственное, что компонент добавляет к
+`CheckboxTreeExtended`:
 
-Используй когда: данные дерева — линейные/сериализуемые (например, из
-бэкенда), нужна стандартная семантика bulk/чек-каскада, не нужны кастомные
-UI-вставки в узлы.
-Не используй когда: нужен кастомный рендер узла (заголовки, иконки,
-доп. контент) — бери `CheckboxTreeExtended` напрямую; нужны 1–2 независимых
-чекбокса (бери `Checkbox` / `CheckboxYGroup`).
+- выбор узла выбирает всех его потомков, снятие — снимает всех;
+- если выбрана только часть потомков, родитель становится выбранным частично
+  (`bulk`) и рисует bulk-иконку вместо галочки;
+- клик по частично выбранному узлу выбирает поддерево целиком, а не снимает
+  выбор;
+- флаги пересчитываются снизу вверх по всему дереву на каждое изменение.
 
----
-
-## Файловая структура
-
-```text
-src/components/CheckboxTree/
-├── CheckboxTree.tsx                    # React.FC обёртка над CheckboxTreeExtended
-├── types.ts                            # ICheckboxTreeCheckboxData
-├── utils.ts                            # traverseCheckboxes, checkParentCheckboxes, checkChildrenCheckboxes
-├── index.ts                            # Barrel: компонент + types + utils
-└── __tests__/
-```
+Используй когда: есть готовая иерархия значений (категории, права доступа,
+фильтры) и нужна стандартная логика «родитель ↔ потомки» без ручного
+пересчёта.
 
-Особенности:
-- **Нет своих стилей** — весь визуальный вид из `CheckboxTreeExtended` и его
-  внутреннего `Checkbox`.
-- **Нет `forwardRef`** — FC без ref-форвардинга. Это осознанное упрощение
-  (потребитель обычно работает с самими `checkboxes` через onChange, не с DOM).
-  Если нужен ref — переключаться на `CheckboxTreeExtended`.
-- **Utils экспортируются через barrel** (`traverseCheckboxes`,
-  `checkParentCheckboxes`, `checkChildrenCheckboxes`) — намеренно, потребитель
-  может использовать их для предварительной обработки данных или тестов.
+Не используй когда: нужна своя структура данных, произвольный контент рядом с
+чекбоксом, ленивая загрузка ветки или другая логика связи родителя и потомков —
+бери `CheckboxTreeExtended` и описывай узлы вручную. Если иерархии нет вовсе,
+достаточно `CheckboxYGroup`.
 
 ---
 
 ## Варианты и props
 
-### `ICheckboxTreeProps extends Omit<ICheckboxTreeExtendedProps, "children" | "onChange">`
-
-Наследует от `CheckboxTreeExtended` всё, кроме `children` (ставится из
-`checkboxes`) и `onChange` (своя сигнатура).
-
-| Prop | Тип | Обязателен | Default | Описание |
-|---|---|---|---|---|
-| `checkboxes` | `ICheckboxTreeCheckboxData[]` | Да | — | Плоский массив (каждый элемент может иметь `children`) — описание дерева. |
-| `onChange` | `(options: ICheckboxTreeCheckboxData[]) => void` | Да | — | Получает **новую копию** массива после каскадной обработки. Потребитель должен сохранить её в свой state. |
-| `size` | `EComponentSize` | Нет | `MD` | Размер чекбоксов (SM/MD/LG). Форвардится в CheckboxTreeExtended. |
-| `children` | `never` | — | — | **Запрещён** через `never` — компонент сам генерирует DOM. |
+`ICheckboxTreeProps` наследует `ICheckboxTreeExtendedProps` без `children` и
+`onChange`, поэтому тип разрешает и остальные атрибуты `<ul>` (`className`,
+`id`, `data-*`). Собственными компонент считает только `checkboxes`, `onChange`
+и `size`, всё остальное уходит через `...rest` на корневой `<ul role="tree">`.
+`className` при этом складывается с внутренними классами, а не заменяет их.
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `checkboxes` | `ICheckboxTreeCheckboxData[]` | — | Описание дерева. Вложенность задаётся полем `children` элементов. Обязателен |
+| `onChange` | `(options: ICheckboxTreeCheckboxData[]) => void` | — | Вызывается после каждого клика по чекбоксу — с новым массивом верхнего уровня и уже пересчитанными флагами. Обязателен |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер чекбоксов и отступов веток. Раздаётся через контекст `CheckboxTreeExtended`, в DOM не попадает. В мобильном представлении всегда `MD` |
+| `children` | `never` | — | Запрещён типом: разметку узлов формирует сам компонент |
+| `ref` | `React.Ref<HTMLUListElement>` | — | Указывает на корневой `<ul role="tree">` |
+| остальные | `React.HTMLAttributes<HTMLUListElement>` | — | Прокидываются на корневой `<ul>` как есть |
 
 ### `ICheckboxTreeCheckboxData`
 
-Единственный тип данных дерева:
-
-```ts
-interface ICheckboxTreeCheckboxData {
-    id: string;                              // уникальный — ключ и aria-поддержка
-    label: React.ReactNode;                  // подпись
-    checked: boolean;                        // текущее состояние
-    bulk?: boolean;                          // "indeterminate", рассчитывается автоматически
-    children?: ICheckboxTreeCheckboxData[];  // рекурсивно
-}
-```
-
-**`bulk` — вычисляется компонентом**, потребитель не должен устанавливать
-его руками. На входе можно передать `false`/`undefined`; после onChange
-массив вернётся с актуальным bulk.
-
----
-
-## Ключевые особенности реализации
-
-### Мутация массива на месте
-
-```ts
-checkbox.checked = checkbox.bulk ? true : checked;
-checkChildrenCheckboxes(checkbox);
-traverseCheckboxes(checkboxes, checkParentCheckboxes);
-onChange([...checkboxes]);
-```
-
-Компонент **мутирует** исходный `checkboxes` массив (меняет `checked`/`bulk`
-на узлах) и только на outer-level передаёт новую ссылку через спред. Это
-значит:
-- Потребитель НЕ должен передавать readonly/immutable данные (Object.freeze
-  сломает).
-- Потребитель должен либо хранить в state `useState` (React сравнит ссылку
-  верхнего уровня), либо всегда клонировать перед передачей.
-- Внутренние референсы не меняются — потомки, которые хранят ссылку на
-  конкретный узел, увидят обновлённое значение.
-
-Это архитектурный компромисс ради простоты алгоритма. **Не рефакторить
-на immutable-подход без серьёзного повода** — сломает внешний контракт.
-
-### `bulk → checked = true` при клике на bulk-узел
-
-```ts
-checkbox.checked = checkbox.bulk ? true : checked;
-```
-
-Клик по узлу в `bulk`-состоянии (частично выбран) делает **всех** потомков
-`checked: true`, не снимает выбор. Это соответствует стандартной UX
-tri-state чекбокса: indeterminate → всё выбрано (не → ничего).
-
-### `checkChildrenCheckboxes` — рекурсивный каскад вниз
-
-```ts
-checkbox.children.forEach((c) => {
-    c.checked = checkbox.checked;
-    checkChildrenCheckboxes(c);
-});
-```
+Описание одного узла. Поля `checked` и `bulk` у узлов с потомками
+пересчитываются компонентом — задавать их вручную имеет смысл только как
+начальное состояние.
 
-После клика на узел все его потомки получают то же `checked`-значение.
-`bulk` у потомков НЕ сбрасывается в этой функции — его потом пересчитает
-`checkParentCheckboxes` при обходе снизу-вверх.
-
-### `checkParentCheckboxes` — каскад вверх (post-order обход)
-
-```ts
-if (c.children) traverseCheckboxes(c.children, cb);
-cb(c);
-```
-
-`traverseCheckboxes` идёт **post-order** (сначала потомки, потом узел) —
-это ключевое: чтобы `checkParentCheckboxes` к моменту обработки узла видел
-актуальное состояние потомков.
-
-Логика узла:
-- Все потомки checked → `checked: true`, `bulk: true` только если у кого-то
-  был bulk (не обычный полный чек).
-- Часть потомков checked → `checked: true, bulk: true`.
-- Никого не checked → `checked: false`.
-
-**Нюанс:** "все checked" с хотя бы одним bulk → родитель тоже bulk. То есть
-bulk распространяется вверх, даже если с точки зрения текущего уровня всё
-выбрано.
-
-### `onChange([...checkboxes])` — shallow clone
-
-```ts
-onChange([...checkboxes]);
-```
+| Поле | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Идентификатор узла, уникальный в пределах всего дерева |
+| `label` | `React.ReactNode` | Видимая подпись чекбокса. За счёт вложенности `<input>` в корневой `<label>` она же становится доступным именем |
+| `checked` | `boolean` | Признак выбора |
+| `bulk` | `boolean` | Признак частичного выбора: bulk-иконка вместо галочки |
+| `children` | `ICheckboxTreeCheckboxData[]` | Вложенные узлы |
 
-Только outer array клонируется — узлы внутри те же мутированные объекты.
-Это совпадает с тем, что нужно React для перерендера при `useState`
-(новая ссылка на массив).
+### Утилиты пересчёта
 
-### render-функция `renderNode` с prev/next linking
+`utils.ts` экспортируется через barrel, поэтому три функции — часть публичного
+API. Они предназначены для случая, когда потребитель считает состояние дерева
+сам; рабочий пример — `stories/Chips/examples/ChipMultiselect/WithCheckboxTreeExample.tsx`,
+где они импортируются из `@sberbusiness/triplex-next` и пересчитывают дерево
+опций внутри `ChipMultiselect`:
 
-```tsx
-<CheckboxTreeExtended.Node
-    prevNodeId={prevCheckbox?.id}
-    nextNodeId={nextCheckbox?.id}
-/>
-```
-
-CheckboxTreeExtended использует prev/next для клавиатурной навигации
-(стрелки вверх/вниз между узлами). CheckboxTree автоматически вычисляет
-их из массива. Это значит, что arrow-navigation работает только в пределах
-одного parent'а — между siblings. **Не менять порядок вызовов в children**:
-первый элемент родителя получает prevNodeId=undefined, и это ожидаемо.
-
-### Функциональный чекбокс через render-проп
+| Функция | Что делает |
+|---|---|
+| `traverseCheckboxes(checkboxes, callback)` | Обход в глубину **снизу вверх**: callback вызывается сначала для потомков, затем для родителя |
+| `checkParentCheckboxes(checkbox)` | Пересчитывает `checked` / `bulk` узла по его прямым потомкам. Узел без потомков не трогает |
+| `checkChildrenCheckboxes(checkbox)` | Проставляет `checked` узла всем его потомкам вниз по дереву |
 
-```tsx
-checkbox={(props) => (
-    <CheckboxTreeExtended.Checkbox {...props} onChange={...} bulk={...} checked={...}>
-        {checkbox.label}
-    </CheckboxTreeExtended.Checkbox>
-)}
-```
+Порядок обхода в `traverseCheckboxes` — не деталь реализации, а контракт:
+`checkParentCheckboxes` работает корректно только если потомки уже пересчитаны.
 
-Node принимает `checkbox` как функцию, получающую provide-props (id,
-aria-атрибуты). CheckboxTree передаёт их наружу и добавляет свои
-onChange/bulk/checked. **Не упрощать** — CheckboxTreeExtended полагается
-на render-проп для управления фокусом и ARIA.
+---
 
-### `onChange={handleChange(checkbox)}` — каррирование
+## Дизайн-токены
 
-Замыкание на конкретный `checkbox` через первый аргумент `handleChange`.
-Позволяет внутри обработчика знать, какой именно узел меняется. Важно:
-`checkbox` — ссылка на объект в массиве, который мутирует. Если потребитель
-заменит массив на новый — замыкание станет устаревшим, но это решается
-новым рендером (новая функция `handleChange` захватит свежий объект).
+Собственных стилей и токенов у компонента нет — он не содержит ни одного
+LESS-модуля. Всё оформление приходит из `CheckboxTreeExtended` (отступы веток,
+общий токен `Checkbox.BorderColor_Focus`) и из `Checkbox` (цвета, размеры,
+состояния). Переопределять их нужно у этих компонентов — см.
+`CheckboxTreeExtended-ai.md` и `Checkbox-ai.md`.
 
 ---
 
 ## Инварианты
 
-- **`children: never`** — не делать компонент композитным, он data-driven.
-  Для композитного — `CheckboxTreeExtended`.
-- **`checkboxes` мутируется на месте** — не передавать Object.freeze /
-  immutable. Не рефакторить на immer/immutability без серьёзного повода.
-- **`bulk` вычисляется автоматически** — не устанавливать руками во
-  входных данных (перезатрётся).
-- **`id` в каждом узле — уникальный** по всему дереву (не просто в рамках
-  одного parent'а). Используется как React `key` и для a11y.
-- **`size` → CheckboxTreeExtended** — наследуется, значение по умолчанию MD.
-- **`onChange` отдаёт новую shallow-copy массива** — не менять на передачу
-  исходной ссылки (сломает `useState`-сравнение).
-- **Post-order обход в `traverseCheckboxes`** — не менять на pre-order,
-  иначе `checkParentCheckboxes` будет работать на неактуальных данных.
-- **`checkbox.checked = checkbox.bulk ? true : checked`** — "bulk → всё в
-  true". Не инвертировать на "bulk → всё в false" без согласования UX.
+- **Компонент мутирует переданные объекты.** `handleChange` пишет `checked` и
+  `bulk` прямо в элементы массива `checkboxes`, а в `onChange` отдаёт поверхностную
+  копию массива верхнего уровня (`[...checkboxes]`). Идентичность самих узлов при
+  этом сохраняется. На этом держится связка с `useState` у потребителя (новая
+  ссылка на массив → перерисовка), и это наблюдаемое поведение: переход на
+  иммутабельный пересчёт — breaking change, а не рефакторинг.
+- **`children` запрещён типом** (`children?: never`). Разметка узлов —
+  ответственность компонента; своя разметка — это `CheckboxTreeExtended`.
+- **`id` узла обязан быть уникальным во всём дереве.** По `id` строятся
+  `prevNodeId` / `nextNodeId`, а по ним `TreeView` ведёт клавиатурную навигацию.
+  Дубликаты ломают перемещение по дереву.
+- **Порядок клавиатурного обхода задаётся порядком массива** на каждом уровне:
+  соседями узла считаются элементы `checkboxes` (или `children`) по соседним
+  индексам.
+- **Дерево всегда полностью раскрыто** — флаг `isStaticCheckboxTreeExtended` в
+  `CheckboxTreeExtended` прячет стрелки и раскрывает все узлы. Сворачивания у
+  `CheckboxTree` нет по построению.
+- **`ref` указывает на корневой `<ul role="tree">`.** Компонент обёрнут
+  `forwardRef`, ссылка проходит насквозь через `CheckboxTreeExtended` →
+  `CollapsibleTreeExtended` → `TreeView`. Собственного DOM-узла у `CheckboxTree`
+  нет, поэтому другого разумного адресата у `ref` тоже нет.
+- **Публичный API** — имена `ICheckboxTreeProps`, `ICheckboxTreeCheckboxData`,
+  функции `traverseCheckboxes`, `checkParentCheckboxes`,
+  `checkChildrenCheckboxes` и состав barrel `index.ts` менять нельзя.
+  `displayName` — `"CheckboxTree"`.
 
 ---
 
-## Accessibility
-
-- Всё управление a11y — внутри `CheckboxTreeExtended` (role="tree"/"treeitem",
-  `aria-checked` (true/false/mixed), клавиатурная навигация).
-- `bulk: true` → `aria-checked="mixed"` (indeterminate-состояние) на узле.
-- `id` узла используется в `aria-controls` / `headers`-подобных связях —
-  обязательно уникален.
-- Навигация:
-  - Tab — переход внутри дерева/наружу.
-  - Space/Enter — toggle чекбокса.
-  - Arrow Up/Down — между siblings через prev/nextNodeId.
-- Если нужна expand/collapse семантика — это задача CheckboxTreeExtended
-  (через Node's expand-проп, если используется).
+## Известные ограничения
+
+Найдено при AI-рефакторинге (TRI-22). Поведение оставлено как есть — его меняют
+только отдельным решением, это публичный контракт.
+
+- **Вход в поддерево с клавиатуры не переводит фокус.** Пока фокус стоит на
+  `<li>` ветки, стрелка вниз меняет активный узел на её потомка, но фокус
+  остаётся на ветке. Причина — guard в `CheckboxTreeExtendedCheckbox`:
+  `if (!document.activeElement?.contains(checkboxNode.current))`. Он защищается
+  от лишнего перевода фокуса при клике мышью, но `contains` истинно и для любого
+  предка, а `<li>` ветки содержит чекбоксы всех своих потомков. При переходе на
+  узел вне текущего поддерева фокус двигается штатно. Лечится на уровне
+  `CheckboxTreeExtended` (сравнивать с самим узлом, а не через `contains`) —
+  наблюдаемое изменение, отдельное решение и запись в release notes.
+  Покрыто тестом `Should move focus between nodes on ArrowDown`, который
+  фиксирует текущее поведение, включая это залипание. Когда ограничение
+  починят, тест упадёт на трёх «холостых» `ArrowDown` в начале — это ожидаемо,
+  его нужно будет переписать под новое поведение.
+- **`bulk` у листа не пересчитывается.** `checkParentCheckboxes` выходит сразу
+  для узла без потомков, поэтому флаг остаётся таким, каким его задал
+  потребитель. Лист с `bulk: true` невозможно снять кликом: `checked` ставится
+  по правилу «клик по частичному выбирает целиком». Задавать `bulk` листу не
+  нужно — флаг осмыслен только для узлов с потомками.
+- **`bulk` не сбрасывается, когда все потомки сняты.** В ветке «не выбран ни
+  один потомок» пишется только `checked = false`. Визуально это незаметно:
+  `Checkbox` показывает иконку (галочку или bulk) только при `checked`, а при
+  следующем выборе флаг всё равно пересчитается.
+- **`<li> cannot appear as a descendant of <li>`** — предупреждение React на
+  первом рендере вложенных узлов. Приходит из `TreeView` и общее для всего
+  семейства (`CollapsibleTree`, `CollapsibleTreeExtended`, `CheckboxTreeExtended`),
+  лечится только на уровне `TreeView`.
 
 ---
 
-## Дизайн-токены
+## Accessibility
 
-Нет своих. Всё через `CheckboxTreeExtended` и внутренний `Checkbox`.
+- Семантику (`<ul role="tree">`, `<li>`, группы) и клавиатурную навигацию
+  обеспечивает `TreeView` через `CheckboxTreeExtended`. `CheckboxTree` добавляет
+  к этому только связывание соседних узлов: каждому `CheckboxTreeExtended.Node`
+  передаются `prevNodeId` и `nextNodeId` соседей по массиву.
+- Фокус при навигации с клавиатуры забирает чекбокс активного узла — это делает
+  `CheckboxTreeExtended.Checkbox`, подробности в `CheckboxTreeExtended-ai.md` →
+  «Accessibility».
+- Подпись чекбокса — поле `label`. Связь подписи и поля структурная: в
+  `Checkbox` корневой элемент — `<label>`, а `<input type="checkbox">` лежит
+  внутри него (`htmlFor` / `id` не используются), поэтому связь работает и при
+  пустом `label` — только доступного имени у такого чекбокса не будет.
+  Собственных текстов компонент не содержит: библиотека мультиязычная, и
+  доступное имя для узла без видимой подписи передаёт потребитель через `label`.
+- Частичный выбор кодируется только визуально (bulk-иконка). `aria-checked="mixed"`
+  компонент не выставляет — под капотом нативный `<input type="checkbox">` без
+  `indeterminate`. Если полумерное состояние нужно ассистивным технологиям,
+  это отдельная доработка `Checkbox`.
 
 ---
 
 ## Связанные компоненты
 
-- `CheckboxTreeExtended` (`src/components/CheckboxTreeExtended`) — нижний
-  уровень, composable, с полным контролем рендера узлов.
-- `Checkbox` (`src/components/Checkbox`) — одиночный чекбокс.
-- `CheckboxYGroup` / `CheckboxXGroup` — группы плоских чекбоксов (без
-  иерархии).
-- `EComponentSize` — общий enum SM/MD/LG.
+- `CheckboxTreeExtended` (`src/components/CheckboxTreeExtended`) — нижний слой и
+  одновременно альтернатива. `ICheckboxTreeProps` наследует его props, а
+  `CheckboxTree` рендерит `CheckboxTreeExtended`, `.Node` и `.Checkbox`. Бери
+  его, когда нужна своя разметка узлов или своя логика связи родителя и
+  потомков.
+- `Checkbox` (`src/components/Checkbox`) — чекбокс каждого узла. Отсюда приходят
+  все токены, размеры и семантика `bulk` (иконка вместо галочки, видимость по
+  `checked`).
+- `CheckboxYGroup` (`src/components/Checkbox`) — плоская вертикальная группа
+  чекбоксов. Подходит, когда иерархии нет и каскадный пересчёт не нужен.
+- `MultiselectField` и `ChipMultiselect` — типовые потребители: показывают
+  `CheckboxTree` как дерево опций внутри выпадающего блока (см. их stories).
 
 ---
 
 ## Stories
 
-`stories/CheckboxTree/CheckboxTree.stories.tsx`
+Основные истории: `stories/CheckboxTree/CheckboxTree.stories.tsx`
 Файлы примеров: `stories/CheckboxTree/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` + управляемое дерево |
-| `Default` | `DefaultExample.tsx` | Базовое дерево с одним уровнем вложенности |
-| `Sizes` | `SizesExample.tsx` | Все три размера чекбоксов |
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` на дереве из трёх веток |
+| `Default` | `DefaultExample.tsx` | Минимальный сценарий: массив в `useState` потребителя, `onChange` передаётся сеттером |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG рядом |
 
 ---
 
@@ -277,7 +218,8 @@ onChange/bulk/checked. **Не упрощать** — CheckboxTreeExtended пол
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-17 | TRI-22: добавлен `forwardRef` на корневой `<ul>` (насквозь через всё семейство Tree), прокидываются html-атрибуты, узел с `children: []` больше не становится выбранным. В «Известные ограничения» добавлено залипание фокуса при входе в поддерево |
+| 2026-09-14 | Создан документ. Проведён AI-рефакторинг (TRI-22): JSDoc на props и полях `ICheckboxTreeCheckboxData`, убраны `eslint-disable` в `utils.ts`, рендер узлов вынесен в общий `renderNodes`; добавлены unit-тесты на утилиты и на каскадный пересчёт |
 
 ---
 

package/bundle/components/CheckboxTreeExtended.md

@@ -114,14 +114,13 @@ Checkbox.BorderColor_Focus
   отрисовывается. Файл и обе ветки кода намеренно оставлены — по TODO флаг
   снимут, когда сворачиваемое дерево станет стандартом. Не удаляй ветки
   `!isStaticCheckboxTreeExtended` как «мёртвый код».
-- **`forwardRef` нет ни у одной части** — `CheckboxTreeExtended`,
-  `.Node` и `.Checkbox` объявлены как `React.FC`. Это осознанно и повторяет
-  `CollapsibleTreeExtended`: под капотом class-компоненты `TreeView` /
-  `TreeViewNode` с собственной работой с DOM. Добавление `forwardRef` меняет
-  форму экспортируемого `ICheckboxTreeExtendedSFC` — это отдельное решение
-  мейнтейнера, а не рефакторинг.
+- **`ref` указывает на корневой `<ul role="tree">`.** Компонент обёрнут
+  `forwardRef`, ссылка уходит в `CollapsibleTreeExtended` и дальше в `TreeView`.
+  У `.Node` и `.Checkbox` своего `forwardRef` по-прежнему нет: `.Node` —
+  class-компонент, `.Checkbox` управляет фокусом сам.
 - **Публичный API** — имена `ICheckboxTreeExtendedProps`,
-  `ICheckboxTreeExtendedSFC`, `ICheckboxTreeExtendedCheckboxProvideProps`,
+  `ICheckboxTreeExtendedFC` (и deprecated-алиас `ICheckboxTreeExtendedSFC`),
+  `ICheckboxTreeExtendedCheckboxProvideProps`,
   `ICheckboxTreeExtendedNodeProps`,
   статические `Checkbox` / `Node` и barrel-экспорты `index.ts` менять нельзя:
   на них опирается `CheckboxTree`, а также stories `Chips` и `MultiselectField`.
@@ -224,6 +223,7 @@ Checkbox.BorderColor_Focus
 | 2026-08-17 | `className` у `CheckboxTreeExtended.Node` больше не затирает собственный класс узла — классы мерджатся через `clsx` (правка по ревью PR #535) |
 | 2026-08-17 | Убран мёртвый селектор `.checkboxTreeCheckbox` из мобильной медиа-выборки (рабочие `> span` и `> svg` оставлены), `.caretIconWrapper:focus` заменён на `:focus-visible` (правки по ревью PR #535) |
 | 2026-08-17 | `ICheckboxTreeExtendedNodeProps` экспортируется — тип уходит в barrel и становится частью публичного API (решение владельца по ревью PR #535) |
+| 2026-09-17 | TRI-22: `CheckboxTreeExtended` обёрнут `forwardRef` — `ref` отдаёт корневой `<ul>`; тип переименован в `ICheckboxTreeExtendedFC`, старое имя оставлено deprecated-алиасом |
 
 ---
 

package/bundle/components/CheckboxXGroup.md

@@ -1,7 +1,7 @@
 ---
 component: CheckboxXGroup
 category: Inputs
-related: [Checkbox]
+related: [Checkbox, CheckboxYGroup]
 tokens: []
 stories: stories/CheckboxXGroup/CheckboxXGroup.stories.tsx
 version: "1.0"
@@ -88,6 +88,7 @@ version: "1.0"
 | 2026-04-16 | Приведение `CheckboxXGroup` к AI-ready: добавлен `forwardRef`, типизирован `children`, созданы AI-документ и инварианты. |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Ключевые особенности реализации» (содержимое перенесено в `Ограничения использования`), переставлены секции, добавлена колонка `Example file` и пустой раздел `Дизайн-токены`. |
 | 2026-08-18 | AI-рефакторинг: JSDoc на props и компоненте, комментарий про кросс-модульный класс `.label` в LESS, добавлены unit-тесты `__tests__/CheckboxXGroup.test.tsx`. Публичный API не изменён. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): добавлены обратные ссылки (`CheckboxYGroup`). Публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/Chip.md

@@ -1,7 +1,7 @@
 ---
 component: Chip
 category: Chips
-related: [ChipGroup, ChipIcon, ChipOptions, ChipSelect, ChipMultiselect, ChipSort, ChipSuggest, ChipDatePicker, ChipMonthYearPicker, ChipClearButton, ChipDropdownArrow, Badge, IconWrapper]
+related: [ChipGroup, ChipOptions, ChipSelect, ChipMultiselect, ChipSort, ChipSuggest, ChipDatePicker, ChipMonthYearPicker, Badge, IconWrapper]
 tokens:
   - Chip.Background_Type1_Default
   - Chip.Background_Type1_Hover
@@ -240,6 +240,7 @@ Default и Hover. Цвет текста (`Color_*`) от типа не зави
 | 2026-07-29 | AI-рефакторинг (TRI-26): codestyle-чистка `Chip.tsx` (константы-маппинги в UPPER_SNAKE_CASE, эквивалентные упрощения в `clsx`, JSDoc на `children` и `handleKeyDown`), unit-тесты расширены с 5 до 22 кейсов; публичный API, DOM и визуал не изменены |
 | 2026-07-29 | Правки по ревью PR #487: уточнена атрибуция класса `.chipGroupItem` (его проставляет семейство Chip*, а не раскладка `ChipGroup`) и описание API `ChipClearButton` / `ChipDropdownArrow` |
 | 2026-09-07 | В семейство добавлен `ChipMonthYearPicker` — упомянут в списках потребителей `Chip` и `.chipGroupItem` |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`ChipIcon`, `ChipClearButton`, `ChipDropdownArrow`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/ChipGroup.md

@@ -1,7 +1,7 @@
 ---
 component: ChipGroup
 category: Chips
-related: [Chip]
+related: [Chip, TagGroup]
 tokens: []
 stories: stories/Chips/ChipGroup.stories.tsx
 version: "1.0"

package/bundle/components/ChipMonthYearPicker.md

@@ -1,7 +1,7 @@
 ---
 component: ChipMonthYearPicker
 category: Chips
-related: [Chip, ChipDatePicker, ChipGroup, MonthYearField, DatePickerExtended]
+related: [Chip, ChipDatePicker, MonthYearField, DatePickerExtended]
 tokens: []
 stories: stories/Chips/ChipMonthYearPicker.stories.tsx
 version: "1.0"
@@ -197,6 +197,7 @@ selected = getPickerValues(value, format, limitRange).calendarDate !== null
 | Дата | Изменение |
 |---|---|
 | 2026-09-07 | Создан компонент и документ (AI-Ready Phase 1) |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`ChipGroup`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 
@@ -216,7 +217,7 @@ export const DefaultExample = () => {
         <ChipMonthYearPicker
             value={value}
             label="MonthYear label"
-            placeholder="мм.гггг"
+            placeholder="Select to proceed"
             onChange={setValue}
             alignment={EDropdownAlignment.LEFT}
             size={EComponentSize.MD}
@@ -248,7 +249,7 @@ const TypeItem = ({ type, label }: TypeItemProps) => {
             <ChipMonthYearPicker
                 value={value}
                 label="MonthYear label"
-                placeholder="мм.гггг"
+                placeholder="Select to proceed"
                 clearButtonProps={{ "aria-label": "Очистить" }}
                 type={type}
                 alignment={EDropdownAlignment.LEFT}
@@ -296,7 +297,7 @@ const SizeItem = ({ size, label }: SizeItemProps) => {
                 alignment={EDropdownAlignment.LEFT}
                 value={value}
                 label="MonthYear label"
-                placeholder="мм.гггг"
+                placeholder="Select to proceed"
                 clearButtonProps={{ "aria-label": "Очистить" }}
                 onChange={setValue}
             />
@@ -332,7 +333,7 @@ export const WithCustomDisplayedValueExample = () => {
         <ChipMonthYearPicker
             value={value}
             label="MonthYear label"
-            placeholder="мм.гггг"
+            placeholder="Select to proceed"
             onChange={setValue}
             alignment={EDropdownAlignment.LEFT}
             size={EComponentSize.MD}

package/bundle/components/ChipMultiselect.md

@@ -1,7 +1,7 @@
 ---
 component: ChipMultiselect
 category: Chips
-related: [Chip, ChipGroup, ChipSelect, MultiselectField, SelectExtendedField]
+related: [Chip, ChipSelect, ChipOptions, MultiselectField, SelectExtendedField]
 tokens: []
 stories: stories/Chips/ChipMultiselect.stories.tsx
 version: "1.0"
@@ -169,6 +169,8 @@ Postfix переключается тем же флагом `selected`: `ChipDro
 - `ChipGroup` — контейнер для ряда чипсов; корневой класс `chipGroupItem`
   проставляется именно ради него.
 - `ChipSelect` — тот же чипс-фильтр, но для выбора одного значения.
+- `ChipOptions` — альтернатива, когда содержимое дропдауна произвольное, а не готовый
+  список значений: тот же `clearSelected` и счётчик, но без собственного target-элемента.
 - `MultiselectField` — родитель по типам и по рендеру: даёт состояние открытости,
   выпадающий блок (`MultiselectField.Dropdown`), focus trap и раздачу размера.
 - `SelectExtendedField` — уровнем ниже `MultiselectField`; из него приходит тип
@@ -202,6 +204,7 @@ Postfix переключается тем же флагом `selected`: `ChipDro
 | Дата | Изменение |
 |---|---|
 | 2026-09-07 | Создан документ (TRI-135). AI-рефакторинг: JSDoc на props и компоненте, мемоизация обработчиков кнопки сброса, порядок импортов; поведение и публичный API не менялись |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`ChipGroup`); добавлены обратные ссылки (`ChipOptions`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---