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

package/bundle/components/Col.md

@@ -0,0 +1,221 @@
+---
+component: Col
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Row, Page, Gap]
+tokens: []
+stories: stories/Col/Col.stories.tsx
+version: "1.0"
+---
+
+# Col
+
+## Назначение
+
+Ячейка responsive-grid, реализованная в духе Bootstrap 4 (12-колоночная
+сетка). Управляет шириной колонки, offset'ом и видимостью через
+breakpoint-префиксы (base / sm / md / lg / xl). Всегда используется
+внутри `Row` (который создаёт flex-контейнер с отрицательными margin'ами
+для компенсации padding'ов Col).
+
+`Col` — FC-обёртка над `<div>` с композицией CSS-классов по пропсам.
+Сами CSS-классы генерируются LESS-миксином `createCol` для всех
+breakpoint-префиксов.
+
+Используй когда: нужна responsive-сетка страницы/формы с точным контролем
+ширины колонок на разных разрешениях.
+Не используй когда: простой flex/grid вручную проще — брать Col только
+ради одной колонки не нужно; для фиксированных отступов между блоками —
+бери `Gap`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Col/
+├── Col.tsx                             # React.FC, нет forwardRef
+├── index.ts                            # Barrel
+├── styles/Col.module.less              # LESS миксин createCol(), генерирует классы
+└── __tests__/
+```
+
+Особенности:
+- **Нет forwardRef** — FC без ref-форвардинга. Это известный AI-ready debt.
+  Не добавлять точечно.
+- **LESS-миксин `createCol(@resolutionType)`** — генерирует 12 column-классов
+  и 12 offset-классов для каждого breakpoint'а. Добавление нового breakpoint —
+  одна строка в LESS.
+- **Bootstrap-подобный API**: `col-1..12`, `col-sm-1..12`, `col-md-*`, `col-lg-*`, `col-xl-*`,
+  `offset-*`, `d-none`, `d-block`.
+
+---
+
+## Варианты и props
+
+### `IColProps extends React.HTMLAttributes<HTMLDivElement>`
+
+**Base (применяется на всех разрешениях):**
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size` | `TColumnSize` (1..12) | `12` | Ширина колонки в 12-ти колоночной сетке. |
+| `offset` | `TOffsetSize` (0..11) | — | Отступ слева в колонках. |
+| `hidden` | `boolean` | — | `display: none !important`. |
+| `block` | `boolean` | — | `display: block !important`. |
+
+**Responsive (каждый breakpoint-префикс дублирует все 4):**
+
+| Breakpoint | Size prop | Offset prop | Hidden prop | Block prop | Media |
+|---|---|---|---|---|---|
+| sm | `sizeSm` | `offsetSm` | `hiddenSm` | `blockSm` | `(min-width: @screen-sm)` |
+| md | `sizeMd` | `offsetMd` | `hiddenMd` | `blockMd` | `(min-width: @screen-md)` |
+| lg | `sizeLg` | `offsetLg` | `hiddenLg` | `blockLg` | `(min-width: @screen-lg)` |
+| xl | `sizeXl` | `offsetXl` | `hiddenXl` | `blockXl` | `(min-width: @screen-xl)` |
+
+**Стандартные:**
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `ReactNode` | Контент колонки. |
+| `className` | `string` | Доп. класс. |
+| `...HTMLDivAttributes` | — | Все стандартные. |
+
+### Types
+
+- `TColumnSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12`
+- `TOffsetSize = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11`
+
+Offset — до 11 (12 offset занял бы всю строку, колонки бы не было).
+
+---
+
+## Ключевые особенности реализации
+
+### `getClassNames` helper
+
+```ts
+function getClassNames({ block, hidden, offset, prefix, size }) {
+    const prefixAsPart = prefix ? `${prefix}-` : "";
+    const prefixVisibility = prefix ? `-${prefix}` : "";
+    // ...
+    if (size) classes.push(`col-${prefixAsPart}${size}`);
+    if (offset !== undefined) classes.push(`offset-${prefixAsPart}${offset}`);
+    if (block) classes.push(`d-block${prefixVisibility}`);
+    if (hidden) classes.push(`d-none${prefixVisibility}`);
+}
+```
+
+**Асимметрия префиксов**: `col-sm-6` (префикс в середине), но `d-block-sm`
+(префикс в конце). Это Bootstrap-ная конвенция, повторённая один-в-один.
+Не менять без миграции пользователей.
+
+### Классы собираются в массив → `styles[...]`
+
+```ts
+const mappedClasses = classNames.map((c) => styles[c]).filter(Boolean);
+```
+
+Имена классов — это ключи в LESS module объекте. `filter(Boolean)`
+защищает от опечаток (если бы класс не существовал → `undefined`).
+
+### `size = 12` по умолчанию
+
+Если size не задан — колонка занимает всю ширину. Это конвенция Bootstrap.
+На узких экранах (без sm/md/lg overrides) колонка всегда full-width,
+что даёт mobile-first сетку.
+
+### `.d-none` / `.d-block` с `!important`
+
+```less
+.d-none { display: none !important; }
+.d-block { display: block !important; }
+```
+
+`!important` нужен, потому что `.col-*` уже имеет `display` (через flex
+item родителя). Без important не переопределяли бы.
+
+### LESS `each` + `range` генерируют классы
+
+```less
+each(range(12), {
+    .col-@{resolutionType}@{value} { ... flex: 0 0 (@base-col * @value); max-width: (...); }
+});
+```
+
+Один миксин — 12 col- + 12 offset-. Вызывается для каждого breakpoint'а.
+**Если добавить XXL** — одна строка `.createCol(xxl-);` в media-query.
+
+### `@grid-horizontal-gap` — не токен, а LESS-переменная
+
+В `src/styles/style.less`. Часть grid-системы (не в список токенов
+компонента). Должен быть синхронизирован с Row'ом (у которого
+отрицательный margin).
+
+---
+
+## Инварианты
+
+- **`size` default = 12** — полная ширина, mobile-first поведение. Не менять.
+- **`TColumnSize` ограничен 1..12** — не расширять. 12 — bootstrap-константа.
+- **`TOffsetSize` ограничен 0..11** — offset=12 бессмыслен.
+- **LESS миксин `createCol`** — источник истины для имён классов. Если
+  переименовывать схему — обновлять **и** миксин, **и** `getClassNames`.
+- **Асимметричные префиксы** `col-sm-*` vs `d-block-sm` — Bootstrap
+  конвенция. Не унифицировать.
+- **`!important` на `.d-none` / `.d-block`** — не удалять.
+- **`Col` всегда внутри `Row`** — работает flex-сеткой. Col без Row
+  получает полную ширину и нет gap-компенсации.
+- **Нет forwardRef** — документированный debt. Не добавлять точечно.
+
+---
+
+## Accessibility
+
+- **Нет ARIA** — div без семантики.
+- **`hidden`** через `display: none` полностью убирает элемент из
+  доступности (screen reader не читает, клавиатура пропускает). Это
+  ожидаемо для скрытия элементов по breakpoint'у.
+- **Порядок DOM = порядок источника**. Если нужно визуально переставить
+  колонки (order), использовать `order` CSS — Col этого не делает сам.
+
+---
+
+## Дизайн-токены
+
+Нет — компонент использует LESS-переменные сетки (`@grid-horizontal-gap`,
+`@screen-sm/md/lg/xl`), не CSS-токены.
+
+---
+
+## Связанные компоненты
+
+- `Row` (`src/components/Row`) — обязательный родитель. Создаёт flex-контейнер
+  с отрицательными margin'ами для Col.
+- `Page` (`src/components/Page`) — страничный layout, часто использует
+  Col/Row внутри для структуры.
+- `Gap` (`src/components/Gap`) — для вертикальных отступов между блоками
+  (Col — горизонтальные колонки).
+
+---
+
+## Stories
+
+`stories/Col/Col.stories.tsx`
+Примеры: `stories/Col/examples/`
+
+Типовые stories:
+- `Default` — колонки равной ширины
+- `Sizes` — разные size на разных breakpoint'ах
+- `Offsets` — с отступами
+- `Hidden/Block` — responsive visibility
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/CollapsableTree.md

@@ -0,0 +1,255 @@
+---
+component: CollapsableTree
+category: Internal
+figma-node: ""
+figma-file: ""
+related: [TreeView, AccordionBase, CheckboxTreeExtended, Spoiler]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# CollapsableTree
+
+## Назначение
+
+Внутренний компонент-"фабрика" для деревьев с раскрывающимися узлами.
+Оборачивает `TreeView` (клавиатурная навигация и активная нода) и подключает
+`AccordionBase` (анимация раскрытия/сворачивания) в каждом узле.
+
+Публично **не используется напрямую** потребителями библиотеки — предоставляет
+основу для `CheckboxTreeExtended` и подобных. Потребитель получает
+render-функции `renderHeader` и `renderBody`, управляя ими формирует DOM
+с кастомной разметкой.
+
+Используй когда: строишь новый tree-based компонент библиотеки, которому
+нужна анимация открытия + клавиатурная навигация.
+Не используй напрямую в приложениях — нестабильный публичный API, бери
+готовый `CheckboxTreeExtended` / `CheckboxTree` / аналог.
+
+---
+
+## Файловая структура
+
+```text
+src/components/CollapsableTree/
+├── CollapsableTree.tsx                     # SFC, обёртка TreeView, compound .Node
+├── components/CollapsableTreeNode.tsx      # Class component, композитит TreeView.Node + AccordionBase
+└── styles/CollapsableTree.module.less      # .collapsableTreeNodeContent.collapsed { visibility: hidden }
+```
+
+Особенности:
+- **Нет `index.ts`** — компонент импортируется напрямую из `CollapsableTree.tsx`
+  (и подкомпонентов). Не стандартизованный барел, потому что внутренний.
+- **Нет `__tests__`** — тесты через потребителей (CheckboxTreeExtended).
+- **Нет stories** — внутренний компонент.
+- **Node — class component**, root CollapsableTree — FC. `Node` использует
+  controlled/uncontrolled паттерн с `state.controlled` флагом, определяемым
+  один раз.
+
+---
+
+## Варианты и props
+
+### Root: `ICollapsableTreeProps extends ITreeViewProps`
+
+Пустое расширение — все пропсы идут в `TreeView`. Смотри `TreeView` для
+полного списка (`navigation`, `activeNodeId`, children).
+
+### Compound: `CollapsableTree.Node` — `ICollapsableTreeNodeProps extends Omit<ITreeViewNodeProps, "children">, Pick<IAccordionBaseProps, "onToggle" | "toggle">`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `renderHeader` | `(props: ICollapsableTreeNodeHeaderProvideProps) => JSX.Element` | Да | Render-функция несворачиваемой части узла. |
+| `renderBody` | `(props: ICollapsableTreeNodeBodyProvideProps) => ReactNode` | Да | Render-функция тела (дочерние узлы / контент). |
+| `opened` | `boolean` | Нет | **Controlled-режим**: определяется в конструкторе по `!== undefined`. |
+| `toggle` | `(opened: boolean) => void` | Нет | Controlled-хендлер. |
+| `onToggle` | `(opened: boolean) => void` | Нет | Срабатывает после анимации (из AccordionBase). |
+| `children` | `never` | — | Запрещён — узлы задаются через renderBody. |
+| `...TreeViewNodeProps` | — | — | Наследует `id`, `prevNodeId`, `nextNodeId`, `activeNode` etc. |
+
+### Provide-props для render-функций
+
+**`ICollapsableTreeNodeBodyProvideProps`:**
+```ts
+{
+    activeNode: boolean;     // активна клавиатурно
+    animating: boolean;      // в процессе анимации
+    hasChildNodes: boolean;  // есть ли дочерние узлы
+    opened: boolean;         // раскрыт ли узел
+    toggle: (opened: boolean) => void;
+}
+```
+
+**`ICollapsableTreeNodeHeaderProvideProps`:**
+```ts
+{
+    activeNode: boolean;
+    animating: boolean;
+    hasChildNodes: boolean;
+    isLastNode: boolean;     // последний в дереве (для декораций)
+    opened: boolean;
+    toggle: (opened: boolean) => void;
+}
+```
+
+Разница — `isLastNode` только в header (используется для разметки линий/
+декораций дерева), `animating` присутствует в обоих.
+
+---
+
+## Ключевые особенности реализации
+
+### `controlled` определяется один раз в конструкторе
+
+```ts
+state = {
+    controlled: typeof this.props.opened !== "undefined",
+};
+```
+
+**Фиксируется в initial state, не пересчитывается.** Переключить
+controlled/uncontrolled на лету нельзя — как и в CardAction, это
+архитектурное ограничение.
+
+### `toggle` замыкание на treeViewNodeProvideProps
+
+```ts
+private toggle = ({ openedNode, setOpenedNode }) => (nextOpened: boolean) => {
+    const opened = controlled ? openedProps : openedNode;
+    if (opened !== nextOpened) {
+        controlled ? toggle?.(nextOpened) : setOpenedNode(nextOpened);
+    }
+};
+```
+
+Возвращает функцию, которая знает, какая нода из TreeView.Node. Внутри
+выбирает: controlled → вызывает внешний `toggle`; uncontrolled → вызывает
+`setOpenedNode` (из TreeView).
+
+**Защита от лишних toggle-вызовов:** `if (opened !== nextOpened)` — не
+вызывает handler, если состояние не изменилось. Важно для AccordionBase,
+который может вызывать toggle при клике на уже открытый заголовок.
+
+### `renderBody` оборачивает в `TreeView.Group` только при hasChildNodes
+
+```tsx
+if (treeViewNodeProvideProps.hasChildNodes) {
+    return <TreeView.Group>{renderBody({...})}</TreeView.Group>;
+}
+return renderBody({...});
+```
+
+`TreeView.Group` нужен для клавиатурной навигации (группировка нод
+одного уровня). Листовые ноды — без Group, чтобы не создавать лишние
+контейнеры.
+
+### `visibility: hidden` в свёрнутом состоянии
+
+```less
+.collapsableTreeNodeContent {
+    &.collapsed {
+        visibility: hidden;
+    }
+}
+```
+
+**Не `display: none`, а `visibility: hidden`.** Причина в комментарии:
+"чтобы по tab не было перехода на скрытые элементы". Но AccordionBase
+даёт `height: 0`, а visibility хорошо сочетается с этим (hidden-элементы
+вне tab-order).
+
+**Важно:** одновременно работают `height: 0` (от ExpandAnimation в
+AccordionBase) + `visibility: hidden` (от CollapsableTree). Если удалить
+`visibility` — элементы внутри свёрнутого узла попадут в tab-order.
+
+### `opened` взаимодействие между AccordionBase и TreeView
+
+```ts
+const opened = controlled ? openedProps : treeViewNodeProps.openedNode;
+// ...
+<AccordionBase isOpen={opened} onToggle={onToggle} ... />
+```
+
+AccordionBase получает "решённый" opened, не оригинальный `openedProps`
+(который может быть undefined в uncontrolled). Это гарантирует, что
+AccordionBase всегда видит boolean.
+
+### `ICollapsableTreeSFC` — кастомный тип
+
+```ts
+interface ICollapsableTreeSFC extends React.FC<ICollapsableTreeProps> {
+    Node: typeof CollapsableTreeNode;
+}
+```
+
+Аналог compound-паттерна Badge/AlertProcess. Присваивание через
+прямую mutation: `CollapsableTree.Node = CollapsableTreeNode`.
+
+---
+
+## Инварианты
+
+- **`controlled` определяется один раз** в state — не пересчитывать на
+  каждом рендере.
+- **`if (opened !== nextOpened)` в toggle** — защита от no-op вызовов
+  AccordionBase. Не удалять.
+- **`TreeView.Group` оборачивает body только при hasChildNodes** — не
+  оборачивать всегда (сломает leaf-ноды).
+- **`visibility: hidden` для .collapsed** — не менять на `display: none`.
+  AccordionBase анимирует через height, display: none сломает анимацию.
+- **`children: never` на Node** — не превращать в композитный.
+  renderHeader/renderBody — единственный способ.
+- **Нет index.ts** — не добавлять для внешнего использования. Держать
+  как внутренний. Если нужен публичный API — делать отдельный компонент-
+  обёртку (как CheckboxTreeExtended).
+- **Class component CollapsableTreeNode** — не переписывать на FC без
+  рефакторинга controlled/uncontrolled init-логики.
+
+---
+
+## Accessibility
+
+Вся a11y делегируется:
+- **TreeView** — `role="tree"`, `role="treeitem"`, клавиатурная навигация
+  (Up/Down через prev/nextNodeId), `activeNode` → focus.
+- **AccordionBase** — `aria-expanded` на заголовке, `aria-controls` ↔ body.
+- **`visibility: hidden`** свёрнутых элементов — вне tab-order и screen
+  reader'ов.
+
+CollapsableTree сам ARIA-атрибуты не добавляет.
+
+---
+
+## Дизайн-токены
+
+Нет. Весь визуал задаёт потребитель через renderHeader/renderBody (стилизует
+свои обёртки). CollapsableTree добавляет только `visibility: hidden`.
+
+---
+
+## Связанные компоненты
+
+- `TreeView` (`src/components/TreeView`) — нижний уровень, клавиатурная
+  навигация и активная нода.
+- `AccordionBase` (`src/components/AccordionBase/protected/AccordionBase`) —
+  анимация раскрытия (ExpandAnimation).
+- `CheckboxTreeExtended` (`src/components/CheckboxTreeExtended`) —
+  основной потребитель.
+- `Spoiler` (`src/components/Spoiler`) — альтернативный раскрывающийся
+  блок без дерева/навигации.
+
+---
+
+## Stories
+
+**Нет собственных stories.** Внутренний компонент — документируется
+косвенно через `CheckboxTreeExtended`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |