@sberbusiness/triplex-next-mcp-server 1.41.0-beta → 1.43.0-beta

package/bundle/components/Checkbox.md

@@ -48,13 +48,15 @@ version: "1.0"
 | `bulk` | `boolean` | `false` | Влияет на отображаемую иконку (используется bulk-иконка). Видимость checkmark всё равно определяется состоянием `checked`. |
 | `size` | `EComponentSize` | `EComponentSize.MD` | Размер: `SM` / `MD` / `LG`. |
 | `children` | `React.ReactNode` | — | Контент лейбла рядом с чекбоксом. Если `children` нет — класс `.nonempty` не применяется. |
-| `labelAttributes` | `React.LabelHTMLAttributes<HTMLLabelElement>` | — | Дополнительные HTML-атрибуты для корневого `<label>` (например, `className`, `onFocus`). |
+| `labelAttributes` | `React.LabelHTMLAttributes<HTMLLabelElement>` | — | Дополнительные HTML-атрибуты для корневого `<label>` (например, `className`, `onFocus`). `labelAttributes.className` объединяется с `className` компонента, а не заменяет его. |
 | `...inputAttributes` | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | Все стандартные атрибуты `<input type="checkbox">` (включая `name`, `onChange`, `aria-label` и т.д.). |
 
 ### Ограничения использования
 
 - DOM-структура фиксирована: корневой `<label>` → `<input type="checkbox">` → декоративные `<span>` / `<svg>` для отрисовки фона и галочки.
 - `ref` прокидывается на внутренний `<input type="checkbox">`.
+- `className` попадает на корневой `<label>`, все остальные props (`...inputAttributes`) — на `<input>`.
+- Размер задаёт классы только на `<label>`: внутренние элементы (`input`, фон, галочка) стилизуются от него как потомки.
 
 ---
 
@@ -84,6 +86,7 @@ version: "1.0"
 - `forwardRef` на компоненте обязателен и должен указывать на `<input>`.
 - Корневой DOM-элемент компонента — `<label>`, внутри которого находится `<input>`.
 - `className` и `size` — публичные части внешнего контрактного API: не менять семантику без согласования.
+- Ховер-стили объявляются только внутри `@media (hover: hover)`: на тач-устройствах браузер эмулирует `:hover` при тапе и не снимает его, из-за чего чекбокс залипал бы в состоянии ховера.
 
 ---
 
@@ -113,6 +116,7 @@ version: "1.0"
 | `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль основных props |
 | `Default` | `DefaultExample.tsx` | Минимальное использование |
 | `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` / `LG` |
+| `VisualTests` | `VisualTestsExample.tsx` | Состояния для visual regression: размеры `SM` / `MD` / `LG` в `checked` и `checked bulk` |
 
 ---
 
@@ -122,6 +126,8 @@ version: "1.0"
 |---|---|
 | 2026-04-16 | Приведение `Checkbox` к AI-ready: соблюдены правила `docs/ai/codestyle.md`, добавлена AI-документация и unit-тест на передачу `className` корневому `label`. |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Ключевые особенности реализации» (содержимое перенесено в `Ограничения использования`), переставлены секции (Accessibility после Инвариантов), добавлена колонка `Example file`. |
+| 2026-08-14 | AI-рефакторинг: выбор иконки галочки через компонент-переменную вместо render-функции, с `<input>` убран не влияющий на стили класс размера, JSDoc на props дополнен дефолтами, расширено unit-покрытие (размеры, `bulk`, `labelAttributes`, `onChange`, `disabled`). |
+| 2026-08-20 | Исправлено залипание ховера на тач-устройствах: правила `:hover` в `Checkbox.module.less` обёрнуты в `@media (hover: hover)`. |
 
 ---
 

package/bundle/components/CheckboxTreeExtended.md

@@ -1,10 +1,9 @@
 ---
 component: CheckboxTreeExtended
 category: Inputs
-figma-node: ""
-figma-file: ""
-related: [CheckboxTree, CollapsableTree, Checkbox]
-tokens: []
+related: [CheckboxTree, CollapsibleTreeExtended, Checkbox]
+tokens:
+  - --triplex-next-Checkbox-BorderColor_Focus
 stories: stories/CheckboxTreeExtended/CheckboxTreeExtended.stories.tsx
 version: "1.0"
 ---
@@ -13,304 +12,203 @@ version: "1.0"
 
 ## Назначение
 
-Декларативное дерево чекбоксов, обёртка над `CollapsableTree` с добавлением
-сетки/отступов под чекбоксы, адаптивного размера и render-props паттерна для
-чекбокса в каждой ноде.
+Низкоуровневое декларативное дерево чекбоксов. Обёртка над
+`CollapsibleTreeExtended` (и, соответственно, над `TreeView`), которая задаёт
+разметку и отступы веток, а размер чекбоксов раздаёт через контекст.
 
-В отличие от `CheckboxTree` (data-driven), здесь потребитель **сам** строит
-JSX-структуру через `CheckboxTreeExtended.Node` + render-функцию
-`checkbox={...}`, управляет `checked`/`onChange` вручную, может вкладывать
-произвольный контент. Это "низкоуровневая" версия.
+Дерево описывается вручную, узел за узлом: каждый узел — это
+`CheckboxTreeExtended.Node` с render-функцией `checkbox`, а вложенные узлы
+передаются в `children`. Состояние чекбоксов (`checked`, `bulk`) целиком на
+стороне потребителя — компонент ничего не хранит и не пересчитывает.
 
-**Важный нюанс:** в текущем релизе дерево **постоянно раскрыто**
-(`isStaticCheckboxTreeExtended = true`). Сворачивание/разворачивание узлов
-пока не поддерживается, стрелка не рендерится. TODO в коде указывает на
-отложенный фичер.
+Используй когда: нужна своя структура данных или своя логика связи родитель ↔
+потомки (частичный выбор, ленивая загрузка ветки, произвольный контент рядом
+с чекбоксом), либо дерево строится из уже готовой разметки.
 
-Используй когда: нужна полная кастомизация рендера (заголовки, иконки,
-доп. контент у нод), управляешь state вручную.
-Не используй когда: нужно простое дерево с плоскими данными — бери
-`CheckboxTree`.
-
----
-
-## Файловая структура
-
-```text
-src/components/CheckboxTreeExtended/
-├── CheckboxTreeExtended.tsx            # React.FC (SFC-интерфейс) + compound Node/Checkbox
-├── CheckboxTreeExtendedContext.ts      # Контекст: {size}
-├── isStaticCheckboxTreeExtended.ts     # const = true, временный feature-flag
-├── index.ts                            # Barrel
-├── styles/CheckboxTreeExtended.module.less
-└── components/
-    ├── CheckboxTreeExtendedNode.tsx    # FC, обёртка CollapsableTree.Node
-    ├── CheckboxTreeExtendedCheckbox.tsx # FC, обёртка Checkbox + фокус-менеджмент
-    └── CheckboxTreeExtendedArrow.tsx   # class Component, стрелка разворачивания (сейчас скрыта)
-```
-
-Особенности:
-- **`ICheckboxTreeExtendedSFC`** — кастомный интерфейс FC с `Checkbox` и
-  `Node` как свойствами. Присваиваются статически после объявления.
-- **`isStaticCheckboxTreeExtended`** — хардкод-константа, временно
-  выключающая сворачивание. **Удалить вместе с файлом**, когда фича будет
-  реализована. Пока что из-за `true` много веток кода идут по "всегда
-  раскрытой" логике.
-- **`useMatchMedia`** — адаптивный размер: на экранах `<= SM_MAX` размер
-  форсируется в `MD` независимо от пропса.
+Не используй когда: достаточно передать массив чекбоксов и получить готовую
+логику каскадного выбора — для этого есть `CheckboxTree`, обёртка поверх этого
+компонента.
 
 ---
 
 ## Варианты и props
 
-### Root: `ICheckboxTreeExtendedProps extends ICollapsableTreeProps`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `size` | `EComponentSize` | `MD` | Размер чекбоксов в дереве (SM/MD/LG). На мобильных (`<= SM_MAX`) перезаписывается на MD. |
-| `className` | `string` | — | Добавочный класс. |
-| `...ICollapsableTreeProps` | — | — | Наследует все пропы CollapsableTree (включая children, navigation). |
+### `CheckboxTreeExtended`
 
-### `CheckboxTreeExtended.Node` — `ICheckboxTreeExtendedNodeProps extends Omit<ICollapsableTreeNodeProps, "children" | "renderBody" | "renderHeader">`
+Наследует `ICollapsibleTreeExtendedProps` (то есть все атрибуты `<ul>`).
 
-| Prop | Тип | Обязателен | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `id` | `string` | Да | Уникальный id ноды. Используется и в навигации CollapsableTree. |
-| `checkbox` | `(props: ICheckboxTreeExtendedCheckboxProvideProps) => JSX.Element` | Да | Render-функция. Получает `active` (клавиатурный фокус) и `opened` (раскрыта ли). |
-| `children` | `React.ReactNode` | Нет | Дочерние `CheckboxTreeExtended.Node`. Если есть — рендерится стрелка (сейчас выключено). |
-| `opened` | `boolean` | Нет | Контролируемое раскрытие. Игнорируется при `isStaticCheckboxTreeExtended=true`. |
-| `prevNodeId` / `nextNodeId` | `string` | Нет | ID соседних нод того же уровня для arrow-навигации. |
-| `...CollapsableTreeNodeProps` | — | — | Всё остальное (кроме `children`/`renderHeader`/`renderBody`). |
-
-### `CheckboxTreeExtended.Checkbox` — `ICheckboxTreeExtendedCheckboxProps extends ICheckboxProps`
-
-Тонкая обёртка над `Checkbox` с дополнениями:
-
-| Prop | Тип | Описание |
-|---|---|---|
-| `active` | `boolean` | Клавиатурный фокус на ноде → автоматически `.focus()` на input. |
-| `opened` | `boolean` | Используется в типах, визуально сейчас не задействовано. |
-| `size` | — | **НЕ передаётся через props**. Подтягивается из контекста CheckboxTreeExtendedContext. |
-| `labelAttributes` | `ICheckboxProps["labelAttributes"]` | Расширяется — добавляется `onFocus` для `stopPropagation`. |
-| `...ICheckboxProps` | — | Все остальные пропы базового Checkbox (checked, bulk, onChange, labelAttributes etc.). |
-
-### `ICheckboxTreeExtendedCheckboxProvideProps`
-
-Что приходит в `checkbox`-render-функцию:
-
-```ts
-interface ICheckboxTreeExtendedCheckboxProvideProps {
-    active?: boolean;   // нода активна (keyboard nav)
-    opened?: boolean;   // нода раскрыта (сейчас всегда true)
-}
-```
-
----
-
-## Ключевые особенности реализации
-
-### `useMatchMedia` для адаптивного size
-
-```ts
-const adaptive = useMatchMedia(
-    `(max-width: ${EScreenWidth.SM_MAX})`,
-    window.innerWidth <= parseInt(EScreenWidth.SM_MAX),
-);
-
-<CheckboxTreeExtendedContext.Provider value={{ size: adaptive ? EComponentSize.MD : size }}>
-```
-
-На мобильных контекст форсирует MD — игнорирует `size`, переданный в пропы.
-Это UX-решение: маленькие чекбоксы на тач-экране неудобны. **Не убирать**
-без дизайн-ревью.
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер чекбоксов и вертикальных отступов веток. Раздаётся через контекст, в атрибуты DOM не попадает |
+| `children` | `React.ReactNode` | — | Узлы `CheckboxTreeExtended.Node` |
+| `className` | `string` | — | Мерджится с собственным классом корневого `<ul>` |
 
-`useMatchMedia` — hook из `src/components/MediaWidth/useMatchMedia`. Второй
-аргумент — initial value для SSR.
+Составные части: `CheckboxTreeExtended.Node` (`CheckboxTreeExtendedNode`) и
+`CheckboxTreeExtended.Checkbox` (`CheckboxTreeExtendedCheckbox`).
 
-### Контекст для size
+### `CheckboxTreeExtended.Node`
 
-Size не передаётся через пропы на `Node` и `Checkbox` — они читают его из
-контекста `CheckboxTreeExtendedContext`. Преимущество: менять в одном
-месте без prop-drilling. Недостаток: `CheckboxTreeExtended.Checkbox` не
-работает вне `CheckboxTreeExtended` (получит initial `MD`).
+Наследует `ICollapsibleTreeExtendedNodeProps` без `children`, `renderBody`,
+`renderHeader` — заголовок и тело узла формирует сам компонент. Тип props
+экспортируется как `ICheckboxTreeExtendedNodeProps` — им типизируют
+собственную обёртку узла.
 
-### `isStaticCheckboxTreeExtended = true` — глобальный флаг
-
-Задействован в **двух местах**:
-
-1. `CheckboxTreeExtendedNode`:
-   - `opened={isStaticCheckboxTreeExtended ? true : opened}` — всегда раскрыто
-   - Стрелка не рендерится
-   - `checkbox` render-функция получает `active: activeNode, opened: true` вместо `active: !children && activeNode, opened`
-
-2. `CheckboxTreeExtendedCheckbox`:
-   - `!isStaticCheckboxTreeExtended && event.stopPropagation()` — не гасит
-     focus bubbling в статичном режиме (ARR-у arrow активна, она сама управляет).
-
-**TODO из кода: удалить файл + константу, когда сворачивание будет готово.**
-До этого любой PR с "давайте сделаем сворачивание" должен **убрать оба места
-использования**, не просто поменять на `false`.
-
-### `handleHeaderMouseDown` — предотвращение фокуса на контейнер
-
-```ts
-if (event.target === event.currentTarget) {
-    event.preventDefault();
-}
-```
-
-Когда клик по области заголовка **сбоку от чекбокса** (а не по самому
-чекбоксу), браузер иначе дал бы фокус контейнеру. Это сбивало бы ARIA
-(фокус должен быть на input). `preventDefault` блокирует это. Проверка
-`target === currentTarget` — фокус блокируется только для прямых кликов в
-контейнер, не для вложенных.
-
-### `useEffect` — auto-focus при `active: true`
-
-```ts
-useEffect(() => {
-    if (!active) return;
-    if (!document.activeElement?.contains(checkboxNode.current as Node)) {
-        checkboxNode.current?.focus();
-    }
-}, [active]);
-```
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `id` | `string` | — | Обязательный идентификатор узла в дереве |
+| `checkbox` | `(props: ICheckboxTreeExtendedCheckboxProvideProps) => JSX.Element` | — | Render-функция чекбокса узла. Обязательна |
+| `children` | `React.ReactNode` | — | Вложенные `CheckboxTreeExtended.Node` |
+| `opened` | `boolean` | — | Игнорируется, пока дерево статично (см. «Инварианты») |
+| `className` | `string` | — | Мерджится с собственным классом узла `<li>` |
+| `prevNodeId` / `nextNodeId` | `string` | — | Порядок узлов для клавиатурной навигации `TreeView` |
 
-Когда дерево получает `active: true` на ноде (через arrow-навигацию
-CollapsableTree), автоматически фокусируется input. Условие
-`!document.activeElement?.contains(...)` — защита от зацикливания focus,
-если уже внутри.
+`ICheckboxTreeExtendedCheckboxProvideProps` — то, что узел передаёт в `checkbox`:
 
-**Нюанс:** `setCheckboxNode` — не forwardRef, а прямой callback-ref. Если
-нужен ref на input снаружи — нельзя передать через `ref={}` на
-`CheckboxTreeExtended.Checkbox` (его не форвардит).
+| Поле | Описание |
+|---|---|
+| `active` | Узел активен при перемещении по дереву с клавиатуры. Нужен, чтобы чекбокс забрал фокус |
+| `opened` | Узел раскрыт. Пока дерево статично — всегда `true` |
 
-### `handleLabelFocus` — stopPropagation
+Эти props положено разворачивать прямо в `CheckboxTreeExtended.Checkbox`
+(`checkbox={(props) => <CheckboxTreeExtended.Checkbox {...props} …>}`) — сам
+чекбокс их обрабатывает и в DOM не пропускает.
 
-```ts
-!isStaticCheckboxTreeExtended && event.stopPropagation();
-```
+### `CheckboxTreeExtended.Checkbox`
 
-Focus на label должен НЕ подниматься до родительской ноды в static-режиме
-(там фокус handle'ится иначе), но должен пузыриться в collapsable-режиме.
-Эта ветка условия активна, только когда включат сворачивание.
+Обёртка над `Checkbox`: добавляет классы дерева, забирает `size` из контекста и
+переводит на себя фокус, когда узел стал активным при навигации с клавиатуры.
+Принимает все props `Checkbox` (`checked`, `bulk`, `onChange`, `disabled`,
+`labelAttributes`, `children` …) плюс служебные `active` и `opened` из
+render-функции узла.
 
-### `CheckboxTreeExtendedArrow` — class component
+`size`, переданный явно, перекрывает размер из контекста — так сделано намеренно
+(spread props идёт после), но в дереве это не нужно и ломает единый ритм.
 
-Class, а не FC — использует `componentDidUpdate` для auto-focus на стрелке
-при `active: true` (аналог `useEffect` в checkbox). Имеет `tabIndex={-1}` —
-фокус не приходит tab'ом, только программно через active.
-
-Клавиатура:
-- `ArrowRight` → toggle(true) (раскрыть)
-- `ArrowLeft` → toggle(false) (свернуть)
-- `Enter`/`Space` → toggle(!opened)
+---
 
-Сейчас не рендерится из-за `isStaticCheckboxTreeExtended`, но код готов.
+## Дизайн-токены
 
-### `createSizeToClassNameMap` для Node header
+Собственных токенов компонент не вводит. Единственная CSS-переменная в стилях —
+у стрелки раскрытия (см. «Инварианты», сейчас не отрисовывается):
 
-```ts
-const sizeToClassNameMap = createSizeToClassNameMap(styles);
 ```
-
-Применяется к `.checkboxTreeExtendedNodeHeader` → класс `.sm/.md/.lg`, от
-которого зависит `margin-bottom` и мобильный padding.
-
-### CSS `:has(.sm)` для глубины отступа
-
-```less
-.checkboxTreeExtendedNode:has(.sm) { margin-left: 16px; }
-.checkboxTreeExtendedNode:has(.md),
-.checkboxTreeExtendedNode:has(.lg) { margin-left: 24px; }
+--triplex-next-Checkbox-BorderColor_Focus
 ```
 
-`:has()` — современный CSS-селектор (Chrome 105+, Safari 15.4+, Firefox 121+).
-В IE и старых браузерах не работает — там отступы будут 0. Поддержка
-браузеров у библиотеки это допускает.
+Размеры и цвета самих чекбоксов приходят из `Checkbox`, вертикальные отступы
+задаются размером узла (`sm` — 8px, `md` / `lg` — 12px), отступ вложенной ветки
+— 16px для `sm` и 24px для `md` / `lg`.
 
 ---
 
 ## Инварианты
 
-- **`isStaticCheckboxTreeExtended = true`** — временная константа. При
-  включении сворачивания удалять файл и убирать ветки из Node/Checkbox.
-- **`size` приходит через контекст, НЕ через пропы Node/Checkbox** — не
-  пробрасывать второй раз.
-- **`useMatchMedia` → MD на мобильных** — не удалять, UX-требование.
-- **`ICheckboxTreeExtendedSFC`** — кастомный тип FC со статическими
-  `.Checkbox`, `.Node`. Без него TS не позволит прямое присваивание.
-- **`event.target === event.currentTarget` + `preventDefault` в
-  handleHeaderMouseDown** — не удалять, отвечает за правильный фокус
-  чекбокса.
-- **Callback-ref в CheckboxTreeExtendedCheckbox** — не менять на forwardRef
-  без понимания: потребители передают свой onChange/checked напрямую, ref
-  на input наружу не проброшен намеренно.
-- **`CheckboxTreeExtendedArrow` — class, не FC** — осознанно: нужен
-  `componentDidUpdate` для focus-эффекта. Не переписывать на FC без
-  понимания лайфцикла CollapsableTree.
-- **`isStaticCheckboxTreeExtended ? true : opened`** в Node — не
-  реверсировать: в static-режиме `opened` игнорируется.
-- **`labelAttributes.onFocus` расширяется handle'ом** — если потребитель
-  передаёт свой `onFocus`, он вызывается **после** internal handle.
-- **`prevNodeId`/`nextNodeId` — для CollapsableTree arrow nav** — если не
-  передать, клавиатурная навигация Up/Down работать не будет.
+- **Дерево статично.** Флаг `isStaticCheckboxTreeExtended = true`
+  (`isStaticCheckboxTreeExtended.ts`) принудительно раскрывает все узлы и
+  прячет стрелку раскрытия: `opened` на узле игнорируется, в `checkbox`
+  всегда приходит `opened: true`, `CheckboxTreeExtendedArrow` не
+  отрисовывается. Файл и обе ветки кода намеренно оставлены — по TODO флаг
+  снимут, когда сворачиваемое дерево станет стандартом. Не удаляй ветки
+  `!isStaticCheckboxTreeExtended` как «мёртвый код».
+- **`forwardRef` нет ни у одной части** — `CheckboxTreeExtended`,
+  `.Node` и `.Checkbox` объявлены как `React.FC`. Это осознанно и повторяет
+  `CollapsibleTreeExtended`: под капотом class-компоненты `TreeView` /
+  `TreeViewNode` с собственной работой с DOM. Добавление `forwardRef` меняет
+  форму экспортируемого `ICheckboxTreeExtendedSFC` — это отдельное решение
+  мейнтейнера, а не рефакторинг.
+- **Публичный API** — имена `ICheckboxTreeExtendedProps`,
+  `ICheckboxTreeExtendedSFC`, `ICheckboxTreeExtendedCheckboxProvideProps`,
+  `ICheckboxTreeExtendedNodeProps`,
+  статические `Checkbox` / `Node` и barrel-экспорты `index.ts` менять нельзя:
+  на них опирается `CheckboxTree`, а также stories `Chips` и `MultiselectField`.
+- **`size` раздаётся только через контекст** `CheckboxTreeExtendedContext`. Не
+  прокидывай его пропом по дереву — узлы и чекбоксы читают контекст сами.
+- **В мобильном представлении размер всегда `MD`** (`useMobileView`), чтобы
+  область нажатия оставалась достаточной. Значение `size` при этом не
+  «запоминается» — оно возвращается при выходе из мобильного представления.
+- **Содержимое узла — только через `checkbox` и `children`.** `renderHeader` /
+  `renderBody` у `CollapsibleTreeExtended.Node` заняты и исключены из типа.
+- **Корневой DOM** — `<ul role="tree">` от `TreeView`, узлы — `<li>`.
 
 ---
 
-## Accessibility
+## Известные ограничения
 
-- Наследует a11y от `CollapsableTree` (role="tree", role="treeitem",
-  aria-expanded).
-- Чекбокс внутри — стандартный (`<input type="checkbox">`), получает
-  `aria-checked` и `aria-checked="mixed"` для bulk.
-- **Клавиатура (CollapsableTree)**:
-  - Arrow Up/Down — навигация между нодами через prev/nextNodeId.
-  - Focus на input при активации ноды.
-- **Клавиатура (CheckboxTreeExtendedArrow)** — зарезервирована, но не
-  активна в static-режиме.
-- **Mobile**: padding 16px вокруг дерева, увеличенная область клика
-  на label (padding-top/bottom 16px) — тач-таргеты.
-- Структура: `.checkboxTreeExtendedNodeHeader` — flex-контейнер с
-  чекбоксом и (будущей) стрелкой.
+Найдено при AI-рефакторинге (TRI-23). Оставлено намеренно — не «чини» их
+походя, по каждому пункту есть решение.
 
----
+- **`CheckboxTreeExtendedArrow` разбирает клавиши через `event.keyCode`**
+  (`EVENT_KEY_CODES`) — устаревший API. Миграция на `event.key` относится ко
+  всему семейству `TreeView`.
+- **`<li> cannot appear as a descendant of <li>`** — предупреждение React на
+  первом рендере вложенных узлов. `<ul role="group">` (`TreeViewGroup`)
+  отрисовывается только при `hasChildNodes`, а он берётся из
+  `abstractNode.getChildren()`, который наполняется, когда дочерние узлы уже
+  смонтировались. Лечится только в `TreeView` и задевает всё семейство
+  (`CollapsibleTree`, `CollapsibleTreeExtended`, `CheckboxTree`,
+  `CheckboxTreeExtended`), поэтому по решению ревьюера оставлено как есть.
+  См. «Accessibility».
 
-## Дизайн-токены
+---
 
-Собственных нет. Чекбокс внутри использует `--triplex-next-Checkbox-*`
-(включая `--triplex-next-Checkbox-BorderColor_Focus` для стрелки).
+## Accessibility
 
-Отступы/размеры — хардкод в LESS (16px/24px mobile padding, 8/12px header
-margin). Кандидат на токенизацию.
+- Семантику и клавиатурную навигацию (стрелки, Home/End, перемещение по узлам)
+  обеспечивает `TreeView`. Компонент добавляет к ней только передачу фокуса.
+- **Фокус при навигации с клавиатуры.** Узел сообщает в render-функцию
+  `active`; `CheckboxTreeExtended.Checkbox` по этому флагу вызывает
+  `focus()` на `<input>`. Правило ровно одно: фокус берётся, когда `active`
+  и текущий `document.activeElement` **не содержит** чекбокс. Mount и update
+  эффект не различает — при монтировании активного узла фокус не уезжает
+  только потому, что `activeElement` по умолчанию `<body>`, а
+  `body.contains(input)` истинно; если в этот момент фокус стоит на
+  постороннем элементе, чекбокс заберёт его сразу на маунте. У стрелки
+  поведение другое — там guard через `prevActive` даёт настоящий
+  mount-иммунитет (фокус только на переходе `active` false → true). Когда
+  флаг статичности снимут, у узлов с детьми фокус вместо чекбокса будет
+  получать стрелка раскрытия.
+- **Клик мимо чекбокса не наводит фокус**: `mousedown` по самому контейнеру
+  заголовка (а не по label/чекбоксу) отменяется через `preventDefault`.
+- Подпись чекбокса — `children` у `CheckboxTreeExtended.Checkbox`, она же
+  связывает `<label>` и `<input>`. Для чекбокса без видимой подписи
+  `aria-label` передаёт потребитель — библиотека мультиязычная.
+- Стрелка раскрытия (пока не отрисовывается) — `role="button"`,
+  `tabIndex={-1}`, обрабатывает `ArrowRight` / `ArrowLeft` (раскрыть /
+  свернуть) и `Enter` / `Space` (инвертировать). Фокус она берёт в `useEffect`
+  (пассивная фаза, после отрисовки), а не в layout-фазе, как было у прежнего
+  class-компонента, — так же, как это делает `CheckboxTreeExtended.Checkbox`.
+- Известное ограничение семейства: на первом рендере вложенные `<li>` попадают
+  внутрь родительского `<li>` без обёртки `<ul role="group">` — `TreeView`
+  добавляет группу только после регистрации дочерних узлов. Поведение общее с
+  `CollapsibleTreeExtended`, лечится на уровне `TreeView`.
 
 ---
 
 ## Связанные компоненты
 
-- `CheckboxTree` (`src/components/CheckboxTree`) — data-driven обёртка.
-  Большинство потребителей берут её, а не extended.
-- `CollapsableTree` (`src/components/CollapsableTree`) — базовое дерево с
-  сворачиванием и клавиатурной навигацией. CheckboxTreeExtended — обёртка
-  над ним.
-- `Checkbox` (`src/components/Checkbox`) — базовый чекбокс.
-- `useMatchMedia` (`src/components/MediaWidth/useMatchMedia`) —
-  responsive-хук.
-- `EScreenWidth` (`src/helpers/breakpoints`) — брейкпойнты.
-- `EComponentSize` — общий enum SM/MD/LG.
+- `CheckboxTree` (`src/components/CheckboxTree`) — обёртка верхнего уровня:
+  принимает массив `ICheckboxTreeCheckboxData` и сама пересчитывает `checked` /
+  `bulk` вверх и вниз по дереву. Если своя структура данных не нужна — бери её.
+- `CollapsibleTreeExtended` (`src/components/CollapsibleTreeExtended`) —
+  нижний слой: узлы, accordion-логика и семантика дерева от `TreeView`.
+  `ICheckboxTreeExtendedProps` наследует `ICollapsibleTreeExtendedProps`.
+- `Checkbox` (`src/components/Checkbox`) — сам чекбокс; `CheckboxTreeExtended.Checkbox`
+  добавляет к нему только классы дерева, размер из контекста и работу с фокусом.
+- `CheckboxTreeExtendedArrow` — внутренняя стрелка раскрытия ветки, из barrel не
+  экспортируется и сейчас не отрисовывается (см. «Инварианты»).
 
 ---
 
 ## Stories
 
-`stories/CheckboxTreeExtended/CheckboxTreeExtended.stories.tsx`
+Основные истории: `stories/CheckboxTreeExtended/CheckboxTreeExtended.stories.tsx`
 Файлы примеров: `stories/CheckboxTreeExtended/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` + ручное управление checked |
-| `Default` | `DefaultExample.tsx` | Базовое дерево 2 уровня |
-| `Sizes` | `SizesExample.tsx` | Все размеры |
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` |
+| `Default` | `DefaultExample.tsx` | Дерево из двух веток с вложенным узлом, состояние чекбоксов в `useState` потребителя |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG рядом |
 
 ---
 
@@ -318,7 +216,10 @@ margin). Кандидат на токенизацию.
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-17 | Создан документ. Проведён AI-рефакторинг: JSDoc на props, `CheckboxTreeExtendedArrow` переведён с class-компонента на FC, добавлен `displayName` у `CheckboxTreeExtendedNode`, класс состояния раскрытия узла берётся из CSS-модуля; добавлены unit-тесты на все части компонента |
+| 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) |
 
 ---
 

package/bundle/components/CheckboxXGroup.md

@@ -36,6 +36,7 @@ version: "1.0"
 
 - Корневой элемент — `<div role="group">`, разметка построена на `inline-flex` и `flex-flow: row wrap`.
 - `indent` управляет применением LESS-класса `indent-{n}` и задаёт отрицательные/положительные маргины для выравнивания сетки.
+- Положительные маргины навешиваются селектором `.indent-{n} .label`, то есть только на потомков с корневым классом `Checkbox`. Для произвольных children (текст, свой контрол, обёртка без `Checkbox` внутри) отступ не применится, а отрицательные маргины контейнера останутся — контент выедет за границы группы.
 
 ---
 
@@ -86,6 +87,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 не изменён. |
 
 ---
 

package/bundle/components/CheckboxYGroup.md

@@ -28,12 +28,16 @@ version: "1.0"
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `children` | `React.ReactNode` | — | Внутри обычно рендерятся `Checkbox` (или компоненты, использующие `Checkbox`). |
-| `...divAttributes` | `React.HTMLAttributes<HTMLDivElement>` | — | Все стандартные HTML-атрибуты для корневого элемента. |
+| `children` | `React.ReactNode` | — | Внутри обычно рендерятся `Checkbox`. Компоненты, оборачивающие `Checkbox`, тоже допустимы, но обёртка вокруг каждого `Checkbox` разрывает соседство `label`-ов и вертикальный отступ пропадает — см. «Ограничения использования». |
+| `...divAttributes` | `Omit<React.HTMLAttributes<HTMLDivElement>, "role">` | — | Стандартные HTML-атрибуты для корневого элемента, кроме `role`: роль всегда `group`. |
 
 ### Ограничения использования
 
 - Корневой элемент — `<div role="group">`, разметка построена на `inline-flex` и `flex-flow: column wrap`.
+- Вертикальный отступ задаётся правилами вида `.checkboxYGroup .label.md + .label.md` (потомковый + соседний комбинатор), поэтому его получают только соседние `label`-элементы `Checkbox` одного размера — на любой глубине вложенности внутри группы. Для произвольных children (текст, свой контрол, обёртка без `Checkbox` внутри) отступ не применится.
+- Обёртка вокруг каждого `Checkbox` (`<Wrapper><Checkbox /></Wrapper>` × 2) разрывает соседство `label`-ов — отступ пропадает. Два `Checkbox` внутри одной общей обёртки отступ, наоборот, получат, хотя прямыми детьми группы не являются.
+- На мобильном брейкпоинте величина внутреннего отступа одинакова для всех размеров, но правила те же — отступ по-прежнему применяется только между соседями одного размера.
+- Там же (`@screen-sm-max`) группа дополнительно получает собственный внешний отступ `margin: 14px 16px` — на десктопе своих внешних отступов у неё нет.
 
 ---
 
@@ -82,6 +86,7 @@ version: "1.0"
 |---|---|
 | 2026-04-16 | Приведение `CheckboxYGroup` к AI-ready: добавлен `forwardRef`, типизирован `children`, созданы AI-документ и инварианты. |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Ключевые особенности реализации» (содержимое перенесено в `Ограничения использования`), переставлены секции, добавлена колонка `Example file` и пустой раздел `Дизайн-токены`. |
+| 2026-08-19 | AI-рефакторинг: JSDoc на props и компоненте, комментарий про кросс-модульные классы `.label`/`.sm`/`.md`/`.lg` в LESS, добавлены unit-тесты `__tests__/CheckboxYGroup.test.tsx`. Публичный API не изменён. |
 
 ---