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

package/bundle/components/TreeView.md

@@ -0,0 +1,224 @@
+---
+component: TreeView
+category: Data Display
+figma-node: ""
+figma-file: ""
+related: [AbstractTree]
+tokens: []
+stories: stories/TreeView/TreeView.stories.tsx
+version: "1.0"
+---
+
+# TreeView
+
+## Назначение
+
+Базовый каркас визуального дерева: семантическая разметка
+(`<ul role="tree">` + `<li role="treeitem">` + `<ul role="group">`) и
+keyboard navigation по вертикали (ArrowUp/ArrowDown). Параллельно
+поддерживает абстрактное дерево (`TreeViewAbstractNode`) для трекинга
+active/opened/tabIndex состояний нод. Контент каждой ноды — render-prop
+(заголовок, иконка, custom-обёртка — на потребителе).
+
+Используй когда: нужно дерево с произвольным content'ом нод. Сам
+TreeView не рисует expand-кнопку и chevron — потребитель использует
+`hasChildNodes`/`openedNode`/`setOpenedNode` из render-prop'а.
+
+---
+
+## Файловая структура
+
+```text
+src/components/TreeView/
+├── TreeView.tsx                       # class TreeView (Component) + ITreeViewComposition
+├── TreeViewContext.tsx                # ITreeViewContext + withTreeViewContext HOC
+├── TreeViewAbstractNode.tsx           # AbstractTreeNode + active/opened/tabIndex
+├── TreeViewAbstractNodeUtils.ts       # навигация по абстрактному дереву
+├── components/
+│   ├── TreeViewNode.tsx               # class TreeViewNodeWithContext (Component) + withTreeViewContext
+│   └── TreeViewGroup.tsx              # FC, <ul role="group">
+└── styles/TreeView.module.less
+```
+
+**Примечание:** в директории нет `index.ts` — импортировать из `./TreeView`,
+`./components/TreeViewNode`, `./components/TreeViewGroup` напрямую (или из
+точки экспорта дизайн-системы, если она настроена в `src/components/index.ts`).
+
+---
+
+## Композиция
+
+```tsx
+<TreeView>
+    <TreeView.Node id="1" prevNodeId={undefined} nextNodeId="2">
+        {({ activeNode, openedNode, hasChildNodes, isLastNode, setOpenedNode }) => (
+            <>
+                <button onClick={() => setOpenedNode(!openedNode)}>
+                    {hasChildNodes ? (openedNode ? "▾" : "▸") : "•"} Node 1
+                </button>
+                {openedNode && (
+                    <TreeView.Group>
+                        <TreeView.Node id="1.1">{/* ... */}</TreeView.Node>
+                    </TreeView.Group>
+                )}
+            </>
+        )}
+    </TreeView.Node>
+    <TreeView.Node id="2" prevNodeId="1">{/* ... */}</TreeView.Node>
+</TreeView>
+```
+
+---
+
+## Публичный API
+
+### `TreeView` (class component)
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `ReactNode` | Дерево из `TreeView.Node` / `TreeView.Group`. |
+| `...HTMLAttributes<HTMLUListElement>` | — | На корневой `<ul role="tree">`. |
+
+Композиция: `TreeView.Node = TreeViewNode`, `TreeView.Group = TreeViewGroup`.
+
+### `TreeView.Node` (`ITreeViewNodeProps`)
+
+```ts
+extends Omit<HTMLAttributes<HTMLElement>, "children">
+```
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | **Обязателен**. Уникальный id ноды. |
+| `children` | `(props: ITreeViewNodeProvideProps) => JSX.Element` | Render-prop — потребитель рисует содержимое. |
+| `opened?` | `boolean` | Внешнее управление раскрытием. Синхронизируется через `componentDidUpdate`. |
+| `prevNodeId?` | `string` | Id соседа слева (для корректной вставки в абстрактное дерево). |
+| `nextNodeId?` | `string` | Id соседа справа. |
+| `...HTMLAttributes<HTMLElement>` | — | На `<li role="treeitem">`. |
+
+#### `ITreeViewNodeProvideProps` (render-prop)
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `activeNode` | `boolean` | Нода активна для keyboard-навигации. |
+| `openedNode` | `boolean` | Раскрыта. |
+| `hasChildNodes` | `boolean` | Есть вложенные `TreeView.Node`. |
+| `isLastNode` | `boolean` | Последняя в полном обходе дерева. |
+| `setOpenedNode` | `(opened: boolean) => void` | Переключение opened. |
+
+### `TreeView.Group` (`ITreeViewGroupProps`)
+
+```ts
+extends HTMLAttributes<HTMLUListElement>
+```
+
+`<ul role="group">` — обёртка для вложенных нод.
+
+### `TreeViewContext` / `withTreeViewContext` / `IWithTreeViewContextProps`
+
+Экспорт контекста и HOC. `withTreeViewContext<T>(Component)` оборачивает
+класс-компонент, передавая `treeViewContext: ITreeViewContext` как props.
+
+### `TreeViewAbstractNode` (class)
+
+Расширяет `AbstractTreeNode<TreeViewAbstractNode>`:
+
+| Метод | Назначение |
+|---|---|
+| `getId()` / id фиксирован в конструкторе | — |
+| `getActive()` / `setActive(boolean)` | Активность для keyboard. |
+| `getOpened()` / `setOpened(boolean)` | Раскрытие. |
+| `getTabIndex()` / `setTabIndex(n)` | Управление roving tabindex (0 для первой ноды первого уровня, -1 — для остальных). |
+
+### `TreeViewAbstractNodeUtils`
+
+Утилиты обхода: `getNode`, `setActiveNode`, `setActiveNextNode`,
+`setActivePrevNode`, `getActiveNode`, `isLastNode`.
+
+---
+
+## Поведение
+
+### Жизненный цикл ноды
+
+`TreeViewNodeWithContext` (class):
+- **constructor:** создаёт `TreeViewAbstractNode({id})`, вызывает `treeViewContext.setOpenedNode(...)` + `registerNode(node, parentNode, prevNode, nextNode)`.
+- **componentDidUpdate:** при изменении `opened` props синхронизирует с абстрактной нодой.
+- **componentWillUnmount:** `treeViewContext.removeNode(node)`.
+
+### Контекст
+
+Каждая нода **переопределяет** `parentNode` в `TreeViewContext.Provider`,
+чтобы дочерние `TreeView.Node` регистрировались в правильном родителе.
+
+### Keyboard navigation
+
+`TreeView.componentDidMount` вешает `window.addEventListener("keydown")`:
+- ArrowDown → `setActiveNextNode` + `preventDefault` + триггер ререндера.
+- ArrowUp → `setActivePrevNode`.
+- Срабатывает только если есть активная нода (`getActiveNode != undefined`).
+
+### Active state и focus
+
+- `<li>` `tabIndex` берётся из `abstractNode.getTabIndex()` (0 для первой первого уровня, -1 — остальных).
+- `onFocus` (event.stopPropagation, чтобы родитель не получил bubble) → `setActiveNode(node, true)`.
+- `onBlur` → `setActiveNode(node, false)`.
+
+### `updateCount` в state
+
+Числовой счётчик, увеличивается при `registerNode` / `setActiveNode` /
+`setOpenedNode` / keyboard навигации. Триггерит ререндер контекста, т.к.
+`abstractNode` — мутируемый объект (изменения не вызывают триггер
+самостоятельно).
+
+⚠️ В коде `prevCount++` (post-increment) — возвращает старое значение,
+поэтому фактически `updateCount` не растёт. Тем не менее `setState` всё
+равно вызывает ререндер, поэтому работает.
+
+---
+
+## Инварианты
+
+- **`TreeView` и `TreeViewNode` — class components**, не FC и не forwardRef. Рефы на `<ul>`/`<li>` приходят через `htmlAttributes` (но не пробрасываются явно).
+- **`TreeView.Node`'s `id` обязателен и должен быть уникальным** во всём дереве.
+- **`prevNodeId`/`nextNodeId` опциональны**, но без них вставка в абстрактное дерево идёт в конец (порядок может разойтись с DOM при динамическом добавлении).
+- **Render-prop `children`** — обязателен (`(props) => JSX.Element`).
+- **`<li role="treeitem">`** + `<ul role="group">` + `<ul role="tree">` — фиксированная семантика по WAI-ARIA `treeview-2a`.
+- **Keyboard listener на `window`** — может конфликтовать с другими компонентами; для multiple TreeView'ов обработчики складываются (срабатывает первый с активной нодой).
+- **Mutable `abstractNode`** — изменения требуют ручного `setState({updateCount})` для ререндера. Не доставать ссылку из contextValue для дальнейшей мутации без `setState`.
+- **`event.stopPropagation` в onFocus/onBlur ноды** — обязательно, чтобы родительский `<li>` не получил bubble.
+- **Композиция через `TreeView.Node = TreeViewNode`** — статические свойства класса.
+- **Опечатка в `prevCount++` (vs `++prevCount`)** — намеренно или нет, не править без анализа поведения.
+- **Нет `index.ts`** в директории — импорты идут напрямую из файлов компонентов.
+
+---
+
+## Accessibility
+
+- Реализовано по WAI-ARIA `treeview-2a` pattern: https://www.w3.org/TR/wai-aria-practices-1.1/examples/treeview/treeview-2/treeview-2a.html
+- `role="tree"` на корне, `role="treeitem"` на `<li>`, `role="group"` на `<ul>`.
+- `aria-expanded={openedNode}` на каждом `<li>`.
+- Roving tabindex (только первая нода первого уровня в tab-стопе).
+- ArrowDown/ArrowUp — навигация по дереву (только при наличии активной ноды).
+- ArrowLeft/ArrowRight (свернуть/раскрыть) — НЕ реализованы; должен делать потребитель в render-prop'е через `setOpenedNode`.
+
+---
+
+## Связанные компоненты
+
+- `AbstractTree` / `AbstractTreeNode` — базовый класс для абстрактного дерева.
+- Любой потребитель — рисует UI ноды (заголовок, кнопка, иконка expand) через render-prop.
+
+---
+
+## Stories
+
+Основные истории: `stories/TreeView/TreeView.stories.tsx`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Triggers.md

@@ -0,0 +1,121 @@
+---
+component: Triggers
+category: Utility
+figma-node: ""
+figma-file: ""
+related: [KeyDownListener]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Triggers (TriggerClickOnKeyDownEvent)
+
+## Назначение
+
+Утилитарный компонент: при нажатии клавиш(и) программно вызывает `.click()`
+на элементе по `targetRef`. Тонкая обёртка над `KeyDownListener` для
+типового сценария "при Enter/Esc/etc — кликни кнопку".
+
+Используй когда: нужно сделать глобальный hotkey для существующей кнопки
+без её рефакторинга. Для произвольного обработчика — использовать
+`KeyDownListener` напрямую.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Triggers/
+└── TriggerClickOnKeyDownEvent.tsx     # FC<ITriggerClickOnKeyDownEventProps>
+```
+
+**Примечание:** в директории нет `index.ts`. Импортировать напрямую:
+`import { TriggerClickOnKeyDownEvent } from ".../Triggers/TriggerClickOnKeyDownEvent"`.
+
+---
+
+## Публичный API
+
+### `ITriggerClickOnKeyDownEventProps`
+
+```ts
+extends Pick<IKeyDownListenerProps, "eventKeyCode">
+```
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `eventKeyCode` | `keyCode \| keyCode[]` | Код клавиши (`EVENT_KEY_CODES.ENTER`, `.ESCAPE`, ...) или массив. |
+| `targetRef` | `RefObject<HTMLButtonElement>` | **Обязателен**. Ссылка на кнопку, которая будет кликнута. |
+| `children` | `ReactElement` | Прокидывается в `KeyDownListener` (обычно — само поддерево, в котором находится targetRef). |
+
+`keyCode` приходит из `EVENT_KEY_CODES` (`utils/keyboard`).
+
+---
+
+## Поведение
+
+```tsx
+<TriggerClickOnKeyDownEvent eventKeyCode={EVENT_KEY_CODES.ENTER} targetRef={btnRef}>
+    <Form>
+        <button ref={btnRef}>Submit</button>
+    </Form>
+</TriggerClickOnKeyDownEvent>
+```
+
+Внутри:
+```tsx
+<KeyDownListener onMatch={handleKeyDown} eventKeyCode={eventKeyCode}>
+    {children}
+</KeyDownListener>
+```
+
+`handleKeyDown`:
+1. Берёт `targetRef.current`.
+2. Если кнопки нет → return.
+3. Проверяет `buttonEl.offsetParent !== null` (элемент видим — нет `display: none` на нём или предке).
+4. Вызывает `buttonEl.click()`.
+
+`KeyDownListener` слушает `keydown` на `window`.
+
+---
+
+## Инварианты
+
+- **`FC, не forwardRef`** — ref не пробрасывается.
+- **`targetRef` обязателен** — без него ничего не произойдёт.
+- **Только `HTMLButtonElement`** — ref типизирован специфично; для других элементов поведение не гарантировано (хоть `.click()` есть на любом HTMLElement).
+- **Проверка `offsetParent !== null`** — защита от триггера на скрытых кнопках. Не путать со `visibility: hidden` (offsetParent остаётся не-null) — для них кнопка всё равно кликнется.
+- **`displayName` выставлен**.
+- **Нет `index.ts`** — импорты напрямую из файла.
+- **`KeyDownListener` слушает на `window`** — глобальный обработчик. Множество `TriggerClickOnKeyDownEvent` со стороны одной и той же клавиши все сработают.
+
+---
+
+## Accessibility
+
+- Программный клик — не заменяет фокус-управление; для accessibility важно, чтобы кнопка была доступна и через Tab.
+- Если кнопка `disabled` — `.click()` не сработает (браузерная защита).
+- Hotkey не объявляется через ARIA — потребитель сам сообщает пользователю о горячих клавишах (например, через подсказку в UI).
+
+---
+
+## Связанные компоненты
+
+- `KeyDownListener` — базовый компонент-слушатель `keydown` на `window`.
+- `ComposedKeyDownListener` — комбинация нескольких слушателей.
+- `EVENT_KEY_CODES` (`utils/keyboard`) — константы клавиш.
+
+---
+
+## Stories
+
+Отдельных stories нет — компонент используется как утилита внутри других сценариев.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/guides/codestyle.md

@@ -0,0 +1,205 @@
+# Codestyle — Triplex-Next
+
+Правила написания кода для AI-агентов и разработчиков.
+Линтер и форматтер применяются автоматически при коммите через `lint-staged`.
+
+---
+
+## Форматирование
+
+Не нужно форматировать вручную — `lint-staged` запустит `prettier --write` при `git commit`.
+
+---
+
+## TypeScript
+
+### Основные правила
+
+- `strict: true` включён — никаких лазеек.
+- **Запрещено:** `any`. Использовать `unknown` + type guard или точный тип.
+- **Запрещено:** non-null assertion (`!`) без объясняющего комментария.
+- **Запрещено:** `as Type` без крайней необходимости. Предпочитать `satisfies`.
+
+В компонентной библиотеке нельзя бросать исключения в рантайме — они упадут у конечного пользователя приложения. Всегда предпочитай правильную типизацию или fallback-значение.
+
+### Именование
+
+| Сущность | Префикс | Пример |
+|---|---|---|
+| Interface | `I` | `IButtonProps`, `IButtonGeneralProps` |
+| Union type | `T` | `TButtonProps` |
+| Enum | `E` | `EButtonTheme`, `EComponentSize` |
+| Константа (модульного уровня) | UPPER_SNAKE_CASE | `DEFAULT_TIMEOUT` |
+| Компонент | PascalCase | `Button`, `DateField` |
+| Хук | camelCase с `use` | `useClickOutside` |
+| Утилита | camelCase | `formatDate`, `uniqueId` |
+
+### Интерфейсы компонента
+
+- Экспортируй интерфейс props — он часть публичного API.
+- Явно указывай тип children если компонент его принимает (`React.ReactNode`).
+
+### Типизация пропов с вариантами (discriminated union)
+
+Если компонент имеет несколько несовместимых тем/режимов — используй discriminated union:
+
+```typescript
+export interface IButtonGeneralProps extends IButtonBaseProps {
+    theme: EButtonTheme.GENERAL | EButtonTheme.SECONDARY;
+    size: EComponentSize;
+}
+
+export interface IButtonLinkProps extends IButtonBaseProps {
+    theme: EButtonTheme.LINK;
+    type?: never; // LINK-кнопка не имеет type
+}
+
+export type TButtonProps = IButtonGeneralProps | IButtonLinkProps;
+```
+
+---
+
+## React
+
+### Обязательные паттерны
+
+- **`forwardRef`** — обязателен на всех UI-компонентах.
+- **Функциональные компоненты** — только. Классовые компоненты не используются.
+- **`clsx`** — для объединения className. Никогда не конкатенировать строки.
+
+```typescript
+// ❌
+className={`${styles.button} ${size === 'sm' ? styles.sm : ''}`}
+
+// ✅
+className={clsx(styles.button, styles[size], { [styles.loading]: loading }, className)}
+```
+
+- Всегда принимай `className` в пропах и прокидывай его в корневой элемент (через spread или явно).
+- Всегда прокидывай `...rest` на семантический элемент.
+
+### Составные компоненты (Compound Components)
+
+Для сложных компонентов с несколькими взаимосвязанными частями (Select + Option, Tabs + Tab + TabPanel) используй паттерн составных компонентов:
+
+```typescript
+// Статические субкомпоненты через Object.assign
+export const Select = Object.assign(
+    React.forwardRef<HTMLDivElement, ISelectProps>((props, ref) => {
+        // ...
+    }),
+    { Option: SelectOption, Group: SelectGroup }
+);
+
+// Использование:
+<Select value={value} onChange={onChange}>
+    <Select.Option value="a">Option A</Select.Option>
+</Select>
+```
+
+### Импорты
+
+В stories/examples и тестах правила разные:
+
+```typescript
+// ✅ В stories/examples, предназначенных для копирования
+import { Button, EButtonTheme } from "@sberbusiness/triplex-next";
+
+// ✅ Внутри src/components
+import { EComponentSize } from "@sberbusiness/triplex-next/enums";
+
+// ✅ В unit-тестах можно импортировать локально, следуя паттерну файла
+import { Button } from "../Button";
+```
+
+Правила:
+- В новых stories/examples, которые показывают копируемый код, импортируй публичный API из `@sberbusiness/triplex-next` или публичных subentry.
+- В unit-тестах и внутреннем коде следуй локальному паттерну файла и предпочитай ближайшие импорты для тестируемого модуля и внутренних зависимостей.
+
+Порядок импортов (prettier-plugin-organize-imports не используется, но придерживайся):
+1. React
+2. Сторонние библиотеки
+3. Внутренние (`@sberbusiness/triplex-next/...`)
+4. Относительные импорты
+5. Стили
+
+---
+
+## LESS (CSS Modules)
+
+### Правила
+
+- Только `.module.less` файлы — никаких глобальных стилей.
+- Имена классов — **camelCase**: `styles.secondaryLight`, `styles.iconOnly`.
+- Никаких **inline styles** в компонентах (в stories допустимо для лейаута примеров).
+- **Цвета** — только через CSS-переменные токенов (`var(--triplex-next-...)`). Никаких hex/rgb.
+- **Переиспользуемые размерные константы** (z-index, отступы страницы, ширины оверлеев) — через LESS-переменные из `src/styles/components/` (`@page-padding-desktop-x`, `@sideOverlayLGWidth` и т.д.). Компонент-специфичные значения (высота кнопки, радиус скругления) можно задавать литералом.
+- `!important` — только в крайнем случае, с комментарием почему.
+
+
+### Применение LESS-переменных (общие размерные константы)
+
+```less
+// ❌ дублируем магическую константу
+.panel {
+    max-width: 864px;
+}
+
+// ✅ берём из src/styles/components/lightbox.less
+@import (reference) "../../styles/components/lightbox";
+
+.panel {
+    max-width: @lightBox-content-max-width-md;
+}
+```
+
+Если нужной константы в `src/styles/components/` нет, а значение используется более чем в одном компоненте — добавь переменную в подходящий файл.
+
+---
+
+## Accessibility
+
+### Мультиязычность: не хардкодь aria-текст
+
+Дизайн-система используется в мультиязычных продуктах. **Никогда не пиши строки на конкретном языке внутри компонента** — ни в `aria-label`, ни в `title`, ни в любом другом атрибуте.
+
+В stories добавляй пример значения для демонстрации — это не хардкод, а иллюстрация:
+
+```typescript
+// В stories/examples/DefaultExample.tsx — пример для документации
+<ModalCloseButton aria-label="Закрыть" />
+```
+
+Если компоненту нужен внутренний текст для связи элементов (например, `aria-labelledby` на диалоге, ссылающийся на заголовок), используй ID-связку, а не текстовый литерал:
+
+### :focus-visible вместо :focus
+
+```less
+// ❌ Показывает outline и при клике мышью
+.button:focus {
+    outline: 2px solid var(--triplex-next-Button-General_Shadow_Focus);
+}
+
+// ✅ Только при клавиатурной навигации
+.button:focus-visible {
+    outline: 2px solid var(--triplex-next-Button-General_Shadow_Focus);
+}
+```
+
+---
+
+## Принципы написания кода
+
+### DRY (Don't Repeat Yourself)
+### KISS (Keep It Simple, Stupid)
+### YAGNI (You Aren't Gonna Need It)
+### Single Responsibility
+
+### Не добавляй без задачи
+
+- Не добавляй docstring/комментарии к коду, который не изменял.
+- Не рефакторь окружающий код без задачи.
+- Не добавляй обработку ошибок для сценариев, которые не могут произойти.
+- Не мигрируй legacy stories/tests на новый шаблон "по пути", если это не часть текущей задачи.
+
+---