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

package/bundle/components/Checkbox.md

@@ -0,0 +1,126 @@
+---
+component: Checkbox
+category: Inputs
+figma-node: ""
+figma-file: ""
+related: [CheckboxXGroup, CheckboxYGroup, CheckboxTree, CheckboxTreeExtended]
+tokens:
+  - --triplex-next-Checkbox-Background_Default
+  - --triplex-next-Checkbox-BorderColor_Default
+  - --triplex-next-Checkbox-Checkmark_Fill_Default
+  - --triplex-next-Checkbox-Background_Hover
+  - --triplex-next-Checkbox-BorderColor_Hover
+  - --triplex-next-Checkbox-Background_Checked_Default
+  - --triplex-next-Checkbox-BorderColor_Checked_Default
+  - --triplex-next-Checkbox-Background_Disabled
+  - --triplex-next-Checkbox-BorderColor_Disabled
+  - --triplex-next-Checkbox-Background_Checked_Disabled
+  - --triplex-next-Checkbox-BorderColor_Checked_Disabled
+  - --triplex-next-Checkbox-Checkmark_Fill_Disabled
+  - --triplex-next-Checkbox-BorderColor_Focus
+  - --triplex-next-Checkbox-Background_Checked_Hover
+stories: stories/Checkbox/Checkbox.stories.tsx
+version: "1.0"
+---
+
+# Checkbox
+
+## Назначение
+Нативный чекбокс в обертке `<label>`, который поддерживает визуальные состояния (default/checked/disabled/focus) и режим частичного выбора через `bulk`.
+
+Используй когда: нужен чекбокс с текстовой подписью (`children`) и стандартным поведением `<input type="checkbox">`.
+Не используй когда: нужен сложный многошаговый выбор или компонент с нестандартной семантикой (тогда лучше другой control).
+
+---
+
+## Варианты и props
+### Опциональные props
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `checked` | `boolean` | — | Состояние чекбокса (controlled). Передаётся через стандартные props `<input>`. |
+| `defaultChecked` | `boolean` | — | Состояние чекбокса (uncontrolled). Передаётся через стандартные props `<input>`. |
+| `disabled` | `boolean` | `false` | Блокирует взаимодействие и меняет визуальное состояние. |
+| `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`). |
+| `...inputAttributes` | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size">` | — | Все стандартные атрибуты `<input type="checkbox">` (включая `name`, `onChange`, `aria-label` и т.д.). |
+
+---
+
+## Ключевые особенности реализации
+### Ref forwarding
+`ref` прокидывается на внутренний `<input type="checkbox">`.
+
+### Иконка
+- `bulk=false` — отрисовывается обычная checkmark-иконка.
+- `bulk=true` — отрисовывается bulk-иконка.
+
+### Структура DOM
+Компонент рендерит:
+1. корневой `<label>`
+2. `<input type="checkbox">`
+3. декоративные `<span>`/`svg` для отрисовки фона и галочки
+
+---
+
+## Accessibility
+Компонент использует нативный `<input type="checkbox">`, поэтому поддерживает стандартную клавиатурную навигацию (Tab + Space) и семантику формы.
+
+Библиотека мультиязычная: текст `aria-label`/`title` не захардкожен в компоненте. При необходимости потребитель передаёт `aria-*` через `...inputAttributes`.
+
+---
+
+## Инварианты
+- `forwardRef` на компоненте обязателен и должен указывать на `<input>`.
+- Корневой DOM-элемент компонента — `<label>`, внутри которого находится `<input>`.
+- `className` и `size` — публичные части внешнего контрактного API: не менять семантику без согласования.
+
+---
+
+## Дизайн-токены
+Компонент использует CSS-переменные:
+`--triplex-next-Checkbox-Background_Default`,
+`--triplex-next-Checkbox-BorderColor_Default`,
+`--triplex-next-Checkbox-Checkmark_Fill_Default`,
+`--triplex-next-Checkbox-Background_Hover`,
+`--triplex-next-Checkbox-BorderColor_Hover`,
+`--triplex-next-Checkbox-Background_Checked_Default`,
+`--triplex-next-Checkbox-BorderColor_Checked_Default`,
+`--triplex-next-Checkbox-Background_Disabled`,
+`--triplex-next-Checkbox-BorderColor_Disabled`,
+`--triplex-next-Checkbox-Background_Checked_Disabled`,
+`--triplex-next-Checkbox-BorderColor_Checked_Disabled`,
+`--triplex-next-Checkbox-Checkmark_Fill_Disabled`,
+`--triplex-next-Checkbox-BorderColor_Focus`,
+`--triplex-next-Checkbox-Background_Checked_Hover`.
+
+---
+
+## Связанные компоненты
+- `CheckboxXGroup` — группировка чекбоксов по оси X.
+- `CheckboxYGroup` — группировка чекбоксов по оси Y.
+- `CheckboxTree` — декларативное дерево чекбоксов (обертка над `CheckboxTreeExtended`), поддерживает bulk-логику и распространение состояния checked по родителям/детям.
+- `CheckboxTreeExtended` — расширенное дерево чекбоксов на базе `CollapsableTree` с Node/Checkbox подкомпонентами (использует нативный `Checkbox` внутри для каждого узла).
+
+---
+
+## Stories
+`stories/Checkbox/Checkbox.stories.tsx`
+Файлы примеров: `stories/Checkbox/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль основных props |
+| `Default` | `DefaultExample.tsx` | Минимальное использование |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `XGroup` | `XGroupExample.tsx` | Группа по оси X |
+| `YGroup` | `YGroupExample.tsx` | Группа по оси Y |
+
+---
+
+## История изменений
+| Дата | Изменение |
+|---|---|
+| 2026-04-16 | Приведение `Checkbox` к AI-ready: соблюдены правила `docs/ai/codestyle.md`, добавлена AI-документация и unit-тест на передачу `className` корневому `label`. |
+

package/bundle/components/CheckboxTree.md

@@ -0,0 +1,280 @@
+---
+component: CheckboxTree
+category: Inputs
+figma-node: ""
+figma-file: ""
+related: [CheckboxTreeExtended, Checkbox, CheckboxYGroup, CheckboxXGroup]
+tokens: []
+stories: stories/CheckboxTree/CheckboxTree.stories.tsx
+version: "1.0"
+---
+
+# CheckboxTree
+
+## Назначение
+
+"Готовый" компонент дерева чекбоксов с автоматической логикой
+checked/bulk-состояний: при клике на родителя все потомки чекаются/
+разчекаются; при частичном выборе потомков родитель получает `bulk: true`
+(состояние "indeterminate").
+
+Является **тонкой data-driven обёрткой** над `CheckboxTreeExtended`:
+потребитель передаёт плоское описание дерева (`ICheckboxTreeCheckboxData[]`),
+компонент сам рендерит `CheckboxTreeExtended.Node` + `.Checkbox`, управляет
+состоянием и отдаёт обновлённый массив в `onChange`.
+
+Используй когда: данные дерева — линейные/сериализуемые (например, из
+бэкенда), нужна стандартная семантика bulk/чек-каскада, не нужны кастомные
+UI-вставки в узлы.
+Не используй когда: нужен кастомный рендер узла (заголовки, иконки,
+доп. контент) — бери `CheckboxTreeExtended` напрямую; нужны 1–2 независимых
+чекбокса (бери `Checkbox` / `CheckboxYGroup`).
+
+---
+
+## Файловая структура
+
+```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`) — намеренно, потребитель
+  может использовать их для предварительной обработки данных или тестов.
+
+---
+
+## Варианты и 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. |
+
+### `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` у потомков НЕ сбрасывается в этой функции — его потом пересчитает
+`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]);
+```
+
+Только outer array клонируется — узлы внутри те же мутированные объекты.
+Это совпадает с тем, что нужно React для перерендера при `useState`
+(новая ссылка на массив).
+
+### render-функция `renderNode` с prev/next linking
+
+```tsx
+<CheckboxTreeExtended.Node
+    prevNodeId={prevCheckbox?.id}
+    nextNodeId={nextCheckbox?.id}
+/>
+```
+
+CheckboxTreeExtended использует prev/next для клавиатурной навигации
+(стрелки вверх/вниз между узлами). CheckboxTree автоматически вычисляет
+их из массива. Это значит, что arrow-navigation работает только в пределах
+одного parent'а — между siblings. **Не менять порядок вызовов в children**:
+первый элемент родителя получает prevNodeId=undefined, и это ожидаемо.
+
+### Функциональный чекбокс через render-проп
+
+```tsx
+checkbox={(props) => (
+    <CheckboxTreeExtended.Checkbox {...props} onChange={...} bulk={...} checked={...}>
+        {checkbox.label}
+    </CheckboxTreeExtended.Checkbox>
+)}
+```
+
+Node принимает `checkbox` как функцию, получающую provide-props (id,
+aria-атрибуты). CheckboxTree передаёт их наружу и добавляет свои
+onChange/bulk/checked. **Не упрощать** — CheckboxTreeExtended полагается
+на render-проп для управления фокусом и ARIA.
+
+### `onChange={handleChange(checkbox)}` — каррирование
+
+Замыкание на конкретный `checkbox` через первый аргумент `handleChange`.
+Позволяет внутри обработчика знать, какой именно узел меняется. Важно:
+`checkbox` — ссылка на объект в массиве, который мутирует. Если потребитель
+заменит массив на новый — замыкание станет устаревшим, но это решается
+новым рендером (новая функция `handleChange` захватит свежий объект).
+
+---
+
+## Инварианты
+
+- **`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.
+
+---
+
+## 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-проп, если используется).
+
+---
+
+## Дизайн-токены
+
+Нет своих. Всё через `CheckboxTreeExtended` и внутренний `Checkbox`.
+
+---
+
+## Связанные компоненты
+
+- `CheckboxTreeExtended` (`src/components/CheckboxTreeExtended`) — нижний
+  уровень, composable, с полным контролем рендера узлов.
+- `Checkbox` (`src/components/Checkbox`) — одиночный чекбокс.
+- `CheckboxYGroup` / `CheckboxXGroup` — группы плоских чекбоксов (без
+  иерархии).
+- `EComponentSize` — общий enum SM/MD/LG.
+
+---
+
+## Stories
+
+`stories/CheckboxTree/CheckboxTree.stories.tsx`
+Файлы примеров: `stories/CheckboxTree/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` + управляемое дерево |
+| `Default` | `DefaultExample.tsx` | Базовое дерево с одним уровнем вложенности |
+| `Sizes` | `SizesExample.tsx` | Все три размера чекбоксов |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |