@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/CheckboxTreeExtended.md

@@ -0,0 +1,321 @@
+---
+component: CheckboxTreeExtended
+category: Inputs
+figma-node: ""
+figma-file: ""
+related: [CheckboxTree, CollapsableTree, Checkbox]
+tokens: []
+stories: stories/CheckboxTreeExtended/CheckboxTreeExtended.stories.tsx
+version: "1.0"
+---
+
+# CheckboxTreeExtended
+
+## Назначение
+
+Декларативное дерево чекбоксов, обёртка над `CollapsableTree` с добавлением
+сетки/отступов под чекбоксы, адаптивного размера и render-props паттерна для
+чекбокса в каждой ноде.
+
+В отличие от `CheckboxTree` (data-driven), здесь потребитель **сам** строит
+JSX-структуру через `CheckboxTreeExtended.Node` + render-функцию
+`checkbox={...}`, управляет `checked`/`onChange` вручную, может вкладывать
+произвольный контент. Это "низкоуровневая" версия.
+
+**Важный нюанс:** в текущем релизе дерево **постоянно раскрыто**
+(`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` независимо от пропса.
+
+---
+
+## Варианты и props
+
+### Root: `ICheckboxTreeExtendedProps extends ICollapsableTreeProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` | Размер чекбоксов в дереве (SM/MD/LG). На мобильных (`<= SM_MAX`) перезаписывается на MD. |
+| `className` | `string` | — | Добавочный класс. |
+| `...ICollapsableTreeProps` | — | — | Наследует все пропы CollapsableTree (включая children, navigation). |
+
+### `CheckboxTreeExtended.Node` — `ICheckboxTreeExtendedNodeProps extends Omit<ICollapsableTreeNodeProps, "children" | "renderBody" | "renderHeader">`
+
+| 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-решение: маленькие чекбоксы на тач-экране неудобны. **Не убирать**
+без дизайн-ревью.
+
+`useMatchMedia` — hook из `src/components/MediaWidth/useMatchMedia`. Второй
+аргумент — initial value для SSR.
+
+### Контекст для size
+
+Size не передаётся через пропы на `Node` и `Checkbox` — они читают его из
+контекста `CheckboxTreeExtendedContext`. Преимущество: менять в одном
+месте без prop-drilling. Недостаток: `CheckboxTreeExtended.Checkbox` не
+работает вне `CheckboxTreeExtended` (получит initial `MD`).
+
+### `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]);
+```
+
+Когда дерево получает `active: true` на ноде (через arrow-навигацию
+CollapsableTree), автоматически фокусируется input. Условие
+`!document.activeElement?.contains(...)` — защита от зацикливания focus,
+если уже внутри.
+
+**Нюанс:** `setCheckboxNode` — не forwardRef, а прямой callback-ref. Если
+нужен ref на input снаружи — нельзя передать через `ref={}` на
+`CheckboxTreeExtended.Checkbox` (его не форвардит).
+
+### `handleLabelFocus` — stopPropagation
+
+```ts
+!isStaticCheckboxTreeExtended && event.stopPropagation();
+```
+
+Focus на label должен НЕ подниматься до родительской ноды в static-режиме
+(там фокус handle'ится иначе), но должен пузыриться в collapsable-режиме.
+Эта ветка условия активна, только когда включат сворачивание.
+
+### `CheckboxTreeExtendedArrow` — class component
+
+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
+
+```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; }
+```
+
+`:has()` — современный CSS-селектор (Chrome 105+, Safari 15.4+, Firefox 121+).
+В IE и старых браузерах не работает — там отступы будут 0. Поддержка
+браузеров у библиотеки это допускает.
+
+---
+
+## Инварианты
+
+- **`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 работать не будет.
+
+---
+
+## 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-контейнер с
+  чекбоксом и (будущей) стрелкой.
+
+---
+
+## Дизайн-токены
+
+Собственных нет. Чекбокс внутри использует `--triplex-next-Checkbox-*`
+(включая `--triplex-next-Checkbox-BorderColor_Focus` для стрелки).
+
+Отступы/размеры — хардкод в LESS (16px/24px mobile padding, 8/12px header
+margin). Кандидат на токенизацию.
+
+---
+
+## Связанные компоненты
+
+- `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.
+
+---
+
+## Stories
+
+`stories/CheckboxTreeExtended/CheckboxTreeExtended.stories.tsx`
+Файлы примеров: `stories/CheckboxTreeExtended/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` + ручное управление checked |
+| `Default` | `DefaultExample.tsx` | Базовое дерево 2 уровня |
+| `Sizes` | `SizesExample.tsx` | Все размеры |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/CheckboxXGroup.md

@@ -0,0 +1,68 @@
+---
+component: CheckboxXGroup
+category: Inputs
+figma-node: ""
+figma-file: ""
+related: [Checkbox]
+tokens: []
+stories: stories/Checkbox/Checkbox.stories.tsx
+version: "1.0"
+---
+
+# CheckboxXGroup
+
+## Назначение
+Компонент-группа для компоновки чекбоксов с направлением по оси `X`.
+Используется как контейнер для нескольких `Checkbox`, когда нужно разложить их в строку с переносами.
+
+---
+
+## Варианты и props
+### Опциональные props
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `indent` | `TIndentSize` | `12` | Отступы/зазоры между чекбоксами в группе. Возможные значения: `12, 16, 20, 24, 28, 32`. |
+| `children` | `React.ReactNode` | — | Внутри обычно рендерятся `Checkbox`. |
+| `...divAttributes` | `React.HTMLAttributes<HTMLDivElement>` | — | Все стандартные HTML-атрибуты для корневого элемента. |
+
+---
+
+## Ключевые особенности реализации
+- Корневой элемент: `<div role="group">`.
+- Разметка: `inline-flex` и `flex-flow: row wrap`.
+- `indent` управляет применением LESS-класса `indent-{n}` и задает отрицательные/положительные маргины для выравнивания сетки.
+
+---
+
+## Accessibility
+- `role="group"` описывает группу взаимосвязанных контролов.
+- Семантика чекбоксов остается нативной на уровне `Checkbox` внутри группы.
+
+---
+
+## Инварианты
+- `forwardRef` обязателен и должен указывать на корневой `<div>`.
+- Корневой DOM-элемент компонента — `<div>`, роль зафиксирована как `role="group"`.
+
+---
+
+## Связанные компоненты
+- `Checkbox` — базовый чекбокс, обычно используется внутри `CheckboxXGroup`.
+
+---
+
+## Stories
+`stories/Checkbox/Checkbox.stories.tsx`
+Файлы примеров: `stories/Checkbox/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `XGroup` | `XGroupExample.tsx` | Группа по оси X |
+
+---
+
+## История изменений
+| Дата | Изменение |
+|---|---|
+| 2026-04-16 | Приведение `CheckboxXGroup` к AI-ready: добавлен `forwardRef`, типизирован `children`, созданы AI-документ и инварианты. |
+

package/bundle/components/CheckboxYGroup.md

@@ -0,0 +1,67 @@
+---
+component: CheckboxYGroup
+category: Inputs
+figma-node: ""
+figma-file: ""
+related: [Checkbox, CheckboxXGroup]
+tokens: []
+stories: stories/Checkbox/Checkbox.stories.tsx
+version: "1.0"
+---
+
+# CheckboxYGroup
+
+## Назначение
+Компонент-группа для компоновки чекбоксов с направлением по оси `Y`.
+Используется как контейнер для нескольких `Checkbox`, когда нужно разложить их вертикально.
+
+---
+
+## Варианты и props
+### Опциональные props
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Внутри обычно рендерятся `Checkbox` (или компоненты, использующие `Checkbox`). |
+| `...divAttributes` | `React.HTMLAttributes<HTMLDivElement>` | — | Все стандартные HTML-атрибуты для корневого элемента. |
+
+---
+
+## Ключевые особенности реализации
+- Корневой элемент: `<div role="group">`.
+- Разметка: `inline-flex` и `flex-flow: column wrap`.
+
+---
+
+## Accessibility
+- `role="group"` описывает группу взаимосвязанных контролов.
+- Семантика чекбоксов остается нативной на уровне `Checkbox` внутри группы.
+
+---
+
+## Инварианты
+- `forwardRef` обязателен и должен указывать на корневой `<div>`.
+- Корневой DOM-элемент компонента — `<div>`, роль зафиксирована как `role="group"`.
+
+---
+
+## Связанные компоненты
+- `Checkbox` — базовый чекбокс, обычно используется внутри `CheckboxYGroup`.
+- `CheckboxXGroup` — аналогичная группа, но с направлением по оси `X`.
+
+---
+
+## Stories
+`stories/Checkbox/Checkbox.stories.tsx`
+Файлы примеров: `stories/Checkbox/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `YGroup` | `YGroupExample.tsx` | Группа по оси Y |
+
+---
+
+## История изменений
+| Дата | Изменение |
+|---|---|
+| 2026-04-16 | Приведение `CheckboxYGroup` к AI-ready: добавлен `forwardRef`, типизирован `children`, созданы AI-документ и инварианты. |
+