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

package/bundle/components/Pagination.md

@@ -0,0 +1,298 @@
+---
+component: Pagination
+category: Navigation
+figma-node: ""
+figma-file: ""
+related: [SelectField, ButtonIcon, ButtonBase, Typography]
+tokens: []
+stories: stories/Pagination/Pagination.stories.tsx
+version: "1.0"
+---
+
+# Pagination
+
+## Назначение
+
+Готовая навигация по страницам с двумя композитными слотами:
+**`PaginationSelect`** (выбор количества элементов на странице) +
+**`PaginationNavigation`** (стрелки prev/next и кнопки страниц с
+ellipsis'ами). Сам `Pagination` — лишь сшивка через
+`PaginationExtended` (контейнер `<nav>`), управление условным
+рендером и проксирование props'ов.
+
+`PaginationExtended` + примитивы (`PaginationNavigationExtended` /
+`Item` / `PaginationPageButton` / `PaginationPageEllipsis` /
+`PaginationNavigationButton`) экспортируются отдельно — для **кастомной
+сборки** пагинации, когда стандартная не подходит.
+
+Используй когда: типичная пагинация над таблицей/списком. Для
+нестандартной — собирай из `PaginationExtended` + примитивов.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Pagination/
+├── Pagination.tsx                              # forwardRef; склейка Select + Navigation
+├── components/
+│   ├── PaginationExtended.tsx                  # forwardRef; <nav> wrapper
+│   ├── PaginationSelect.tsx                    # forwardRef; SelectField (size SM)
+│   ├── PaginationNavigation.tsx                # forwardRef; prev/pages/next + ellipsis
+│   ├── PaginationNavigationExtended.tsx        # forwardRef; <ul>
+│   ├── PaginationNavigationExtendedItem.tsx    # forwardRef; <li>
+│   ├── PaginationNavigationButton.tsx          # forwardRef; ButtonIcon SQUIRCLE + caret-icon
+│   ├── PaginationPageButton.tsx                # forwardRef; ButtonBase + Text B3
+│   └── PaginationPageEllipsis.tsx              # forwardRef; Text B3 "..."
+├── utils/paginationUtils.tsx                   # createPagesArray + generateRange + PAGINATION_ELLIPSIS_VALUE
+├── enums.ts                                    # EPaginationNavigationIconDirection (BACK | NEXT)
+├── index.ts                                    # Barrel: всё
+├── styles/*.module.less
+└── __tests__/
+```
+
+---
+
+## Compound-структура
+
+```tsx
+<Pagination
+    paginationSelectProps={{
+        paginationLabel: "На странице",
+        value: pageSize,
+        options: [
+            { value: 10, label: "10" },
+            { value: 25, label: "25" },
+        ],
+        onChange: setPageSize,
+    }}
+    paginationNavigationProps={{
+        currentPage,
+        totalPages,
+        onCurrentPageChange: setCurrentPage,
+        boundaryCount: 1,
+        siblingCount: 1,
+    }}
+/>
+```
+
+Кастомная сборка:
+
+```tsx
+<PaginationExtended>
+    <PaginationNavigationExtended>
+        <PaginationNavigationExtendedItem>
+            <PaginationNavigationButton direction={EPaginationNavigationIconDirection.BACK} />
+        </PaginationNavigationExtendedItem>
+        <PaginationNavigationExtendedItem>
+            <PaginationPageButton isCurrent>1</PaginationPageButton>
+        </PaginationNavigationExtendedItem>
+        ...
+    </PaginationNavigationExtended>
+</PaginationExtended>
+```
+
+---
+
+## Варианты и props
+
+### Pagination — `IPaginationProps extends IPaginationExtendedProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `paginationSelectProps?` | `IPaginationSelectProps` | Если **не передан** — Select не рендерится. |
+| `paginationNavigationProps` | `IPaginationNavigationProps` | Обязателен. Если `totalPages <= 1` — Navigation не рендерится. |
+| `...IPaginationExtendedProps` | `HTMLAttributes<HTMLElement>` | На `<nav>`. |
+
+### PaginationSelect — `IPaginationSelectProps`
+
+```ts
+extends Omit<ISelectFieldProps, "size" | "value">
+extends Required<Pick<ISelectFieldProps, "value">>
+```
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `paginationLabel` | `ReactNode` | Лейбл слева от селекта (`<Text size=B3 id={instanceId}>`). |
+| `value` | `ISelectFieldProps["value"]` | Обязательно. |
+| `options`, `onChange`, ... | от SelectField | — |
+
+- **`size` захардкожен `EComponentSize.SM`**.
+- **`mobileTitle = paginationLabel`** — тот же текст для мобильного header'а.
+- **`targetProps.fieldLabel = ""`** — лейбл внутри SelectField очищается (label рисуется отдельно слева).
+- **`aria-labelledby={instanceId}`** + `Text id={instanceId}` — связь label ↔ control.
+- `instanceId = "Pagination-{lodash uniqueId()}"` — **SSR-небезопасно** (два рендера дадут разные id, гидрация может ругаться).
+
+### PaginationNavigation — `IPaginationNavigationProps extends HTMLAttributes<HTMLUListElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `currentPage` | `number` | — | Контролируемая текущая страница (1-based). |
+| `totalPages` | `number` | — | Всего страниц. |
+| `onCurrentPageChange` | `(page: number) => void` | — | Сеттер. |
+| `boundaryCount` | `number` | `0` | Сколько страниц всегда показывать в начале и в конце. |
+| `siblingCount` | `number` | `0` | Сколько соседей слева/справа от текущей. |
+| `buttonPrevProps?` | `Omit<IPaginationNavigationButtonProps, "direction" \| "children">` | — | Доп. props на кнопку «назад». |
+| `buttonNextProps?` | `Omit<...>` | — | Доп. props на «вперёд». |
+
+- **prev disabled при `currentPage === 1`** (или `buttonPrevProps?.disabled`).
+- **next disabled при `currentPage === totalPages`** (или `buttonNextProps?.disabled`).
+- Рендерит prev → массив страниц от `createPagesArray(...)` → next.
+
+### PaginationNavigationButton — `IPaginationNavigationButtonProps`
+
+```ts
+extends Omit<IButtonIconProps, "shape" | "active" | "children">
+children?: never
+direction: EPaginationNavigationIconDirection
+```
+
+- Иконка: `CaretleftStrokeSrvIcon24 paletteIndex={5}`. Для `NEXT` — добавляется `styles.directionIconNext` (поворот через CSS).
+- `shape={EButtonIconShape.SQUIRCLE}` — захардкожен.
+- `children?: never` — фиксированная иконка.
+
+### PaginationPageButton — `TPaginationPageButtonProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `isCurrent?` | `boolean` | Подсветка текущей. **`aria-live="polite"`** при `isCurrent` — screen reader озвучит при смене. |
+| `children` | `ReactNode` | Номер страницы. |
+| `onClick` | `() => void` | Клик. |
+
+- Содержимое — `<Text size=B3>`.
+
+### PaginationPageEllipsis — `IPaginationPageEllipsis extends HTMLAttributes<HTMLSpanElement>`
+
+- `<Text size=B3>...children...</Text>`. Контракт: `children = "..."` — чисто визуальный плейсхолдер.
+
+### PaginationExtended — `IPaginationExtendedProps extends HTMLAttributes<HTMLElement>`
+
+- `<nav>` контейнер. `data-tx={pkg.version}`.
+
+### PaginationNavigationExtended/Item
+
+- `<ul>` / `<li>` — семантический список для пагинации.
+
+### enums.ts
+
+- `EPaginationNavigationIconDirection.BACK | NEXT` (numeric enum: 0/1).
+
+---
+
+## Ключевые особенности реализации
+
+### Условный рендер слотов
+
+```tsx
+{paginationSelectProps && <PaginationSelect {...paginationSelectProps} />}
+{paginationNavigationProps.totalPages > 1 && <PaginationNavigation {...paginationNavigationProps} />}
+```
+
+- Select — опциональный.
+- Navigation — рендерится только при `totalPages > 1` (на 1 странице — нечего листать).
+
+### `PaginationUtils.createPagesArray`
+
+```ts
+// startPages | (ellipsis | next page) | siblings around current | (ellipsis | prev page) | endPages
+```
+
+- `boundaryCount` — кол-во **всегда видимых** в начале/конце.
+- `siblingCount` — кол-во **соседей** вокруг текущей.
+- Если соседи примыкают к boundary — ellipsis заменяется на одну страницу (без «1 ... 2 3 4» — будет «1 2 3 4»).
+- Возвращает массив `number[]`, где **`PAGINATION_ELLIPSIS_VALUE = -1`** — sentinel для ellipsis.
+- Использует `lodash-es/range`.
+
+### Sentinel `-1` для ellipsis
+
+```ts
+case PAGINATION_ELLIPSIS_VALUE: return <PaginationPageEllipsis>...</PaginationPageEllipsis>;
+default: return <PaginationPageButton>{page}</PaginationPageButton>;
+```
+
+- Магическое значение `-1` — публично экспортируется как `PAGINATION_ELLIPSIS_VALUE`.
+
+### `aria-live="polite"` на текущей кнопке
+
+```tsx
+aria-live={isCurrent ? "polite" : undefined}
+```
+
+- При смене `currentPage` screen reader озвучит новую кнопку.
+
+### Иконка NEXT — поворот через CSS
+
+```tsx
+{isDirectionBack ? <CaretleftStrokeSrvIcon24 ... /> : <CaretleftStrokeSrvIcon24 className={styles.directionIconNext} />}
+```
+
+- Только одна иконка (`CaretleftStrokeSrvIcon24`); для NEXT — поворот на 180° через `styles.directionIconNext`.
+
+### `aria-labelledby` через `uniqueId`
+
+```ts
+const [instanceId] = useState(() => `Pagination-${uniqueId()}`);
+```
+
+- **SSR-небезопасно**: lodash `uniqueId` глобальный счётчик.
+- Решает связь Text-label ↔ SelectField через `aria-labelledby`.
+
+---
+
+## Инварианты
+
+- **`Pagination.totalPages > 1`** — Navigation рендерится; иначе скрыт.
+- **`paginationNavigationProps`** — обязательный prop (тип, не optional).
+- **`paginationSelectProps`** — опционален; отсутствие = нет селекта.
+- **`PAGINATION_ELLIPSIS_VALUE = -1`** — публичная константа-sentinel.
+- **`PaginationSelect.size = SM`** — захардкожен.
+- **`PaginationSelect.targetProps.fieldLabel = ""`** — внутренний label очищается.
+- **`PaginationNavigationButton.shape = SQUIRCLE`**, иконка `CaretleftStrokeSrvIcon24` — фиксированы; `children: never`.
+- **`PaginationPageButton.aria-live="polite"`** при `isCurrent` — публичный a11y-контракт.
+- **`uniqueId()`** в SelectId — SSR-небезопасно.
+- **`<nav>` корень PaginationExtended** + `<ul>`/`<li>` для Navigation — семантическая структура.
+- **`createPagesArray` зависит от lodash-es `range`**.
+- **`EPaginationNavigationIconDirection`** — numeric enum (0/1), не string.
+- **ForwardRef** на всех уровнях.
+
+---
+
+## Accessibility
+
+- `<nav>` корень + `<ul>`/`<li>` элементы — корректная семантика навигации/списка.
+- `aria-live="polite"` на текущей странице — озвучивание при смене.
+- `aria-labelledby` связывает label PaginationSelect с самим SelectField.
+- **Нет `aria-label="Pagination"`** на `<nav>` — потребитель должен передать через `...rest` (иначе screen reader скажет просто «navigation»).
+- **Иконки prev/next без `aria-label`** — `ButtonIcon` сам по себе не озвучивает направление. Потребитель должен передать `buttonPrevProps={{ "aria-label": "Предыдущая" }}` и т.п.
+- `disabled` корректно через `<button disabled>` — клавиатура и SR обработают.
+
+---
+
+## Дизайн-токены
+
+Нет собственных — наследуются от `Button`, `Text`, `SelectField`.
+
+---
+
+## Связанные компоненты
+
+- `SelectField` — нижележащий control в PaginationSelect.
+- `ButtonIcon`, `ButtonBase` — кнопки.
+- `Text` (Typography) — текст.
+- `CaretleftStrokeSrvIcon24` — единственная иконка стрелки.
+- `lodash-es/range`, `lodash-es/uniqueId`.
+
+---
+
+## Stories
+
+`stories/Pagination/Pagination.stories.tsx`
+Примеры: `stories/Pagination/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Portal.md

@@ -0,0 +1,119 @@
+---
+component: Portal
+category: Utilities
+figma-node: ""
+figma-file: ""
+related: [ModalWindow, LightBox, Dropdown, Tooltip]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Portal
+
+## Назначение
+
+Тонкая обёртка над `ReactDOM.createPortal`. Рендерит `children` во
+внешний DOM-узел (`container`), оставаясь в текущем React-дереве
+(контекст, обработчики, focus-trap работают как обычно).
+
+Используй когда: нужен node вне родительского дерева (обход
+`overflow: hidden`, `z-index`-стэк, поверх модалок). В большинстве
+случаев напрямую — внутри `ModalWindow`/`Dropdown`/`Tooltip`/`LightBox`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Portal/
+├── Portal.tsx   # FC, 1 строка — createPortal
+└── index.ts     # Barrel
+```
+
+Нет стилей, тестов, stories.
+
+---
+
+## Варианты и props
+
+### `IPortalProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | Да | Рендерится в `container`. |
+| `container` | `Element \| DocumentFragment` | Да | Целевой DOM-узел. |
+
+Никаких опциональных props или fallback'ов.
+
+---
+
+## Ключевые особенности реализации
+
+### `ReactDOM.createPortal`
+
+```tsx
+export const Portal = ({ children, container }) => ReactDOM.createPortal(children, container);
+```
+
+- React сам управляет mount/unmount через виртуальное дерево.
+- **Контекст-провайдеры**, **events bubbling** работают, как если бы дерево было локальным (events bubble через React-tree, не DOM-tree).
+
+### `container` — обязателен
+
+- В отличие от ряда библиотек, `Portal` **не создаёт** контейнер сам и **не подбирает** `document.body` по умолчанию.
+- Потребитель сам решает, куда монтировать (типичный паттерн: создать `<div>` в `document.body` и передать сюда).
+
+### **Не SSR-safe**
+
+- `createPortal` на сервере выбрасывает ошибку. При SSR — потребитель должен оборачивать в `if (typeof window !== "undefined")` или использовать `useEffect`.
+- В этом проекте — обычно через `useEffect` создают и монтируют контейнер (см. `ModalWindow`, `LightBox`).
+
+### **Никаких lifecycle-хуков**
+
+- Portal не отслеживает изменение `container`. При смене `container` — React удалит старый child из старого container и смонтирует в новый (стандартное поведение createPortal).
+
+---
+
+## Инварианты
+
+- **`container` — обязателен**, не optional.
+- **`children` — `ReactNode`**, не `ReactElement` (можно массив, fragment, primitive).
+- **`FC`, не `forwardRef`** — ref на children идёт нативно через React-tree, на сам Portal-component — нет.
+- **Не SSR-safe** — потребитель ответственен за условный рендер.
+- **Контейнер не создаётся автоматически** — приходит снаружи.
+- **Никаких side effects** — нет `useEffect`, нет mount-классов, нет cleanup.
+
+---
+
+## Accessibility
+
+- Portal не влияет на семантику. **Focus management, ARIA-связи** — задача потребителя.
+- Tab-последовательность определяется DOM-порядком: portal'ed узел — там, куда смонтирован, не там, где находится в JSX. Это часто нарушает focus order — нужен focus-trap внутри.
+
+---
+
+## Дизайн-токены
+
+Нет.
+
+---
+
+## Связанные компоненты
+
+- `ModalWindow` / `LightBox` / `Dropdown` / `Tooltip` — все используют Portal.
+- `react-dom` `createPortal` — нативный API.
+
+---
+
+## Stories
+
+Нет.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Radio.md

@@ -0,0 +1,174 @@
+---
+component: Radio
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [Checkbox, RadioYGroup, RadioXGroup, Typography, FormField]
+tokens: []
+stories: stories/Radio/Radio.stories.tsx
+version: "1.0"
+---
+
+# Radio
+
+## Назначение
+
+Радио-кнопка: нативный `<input type="radio">` с visually-hidden default'ом
++ кастомная иконка (`<span>` со стилями) + опциональный текст-описание
+(через `Text`). Сгруппировать кнопки можно горизонтально (`RadioXGroup`)
+или вертикально (`RadioYGroup`) — оба контейнера дают `role="radiogroup"`.
+
+Используй когда: выбор одного варианта из небольшого набора (если
+больше ~5 — `SelectField`). Для multi-choice — `Checkbox` + `RadioYGroup`-
+аналог.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Radio/
+├── Radio.tsx           # forwardRef<HTMLInputElement>; <label> + <input> + <span> + <Text>
+├── RadioXGroup.tsx     # FC; <div role="radiogroup"> + indent (12-32)
+├── RadioYGroup.tsx     # FC; <div role="radiogroup">
+├── styles/Radio.module.less + RadioXGroup + RadioYGroup
+├── index.ts            # Barrel
+└── __tests__/
+```
+
+---
+
+## Варианты и props
+
+### Radio — `IRadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` | Размер кнопки + связанный размер `Text`. |
+| `labelAttributes?` | `LabelHTMLAttributes<HTMLLabelElement>` | — | Атрибуты на `<label>` (className мержится). |
+| `children?` | `ReactNode` | — | Текст-описание справа от радио. Если пуст — текст не рендерится, label получает класс без `nonempty`. |
+| `disabled?` | `boolean` | — | Прокидывается в `<input>` + добавляет класс `disabled` на label. |
+| `...inputAttributes` | `InputHTMLAttributes<HTMLInputElement>` | — | Все остальные `<input>`-атрибуты (`name`, `value`, `checked`, `onChange`, ...). |
+
+- **`type` исключён** — всегда `"radio"`.
+- **`size` исключён из `InputHTMLAttributes`** — наш собственный enum, не нативный.
+- ForwardRef → `<input>`.
+
+### Маппинг `size` → текст:
+
+| `size` | `Text size` |
+|---|---|
+| `LG` | `B2` |
+| `MD` | `B3` |
+| `SM` | `B4` |
+
+### RadioXGroup — `IRadioXGroupProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `indent` | `TIndentSize` (`12 \| 16 \| 20 \| 24 \| 28 \| 32`) | `12` | Горизонтальный gap (в `px`, через CSS-классы `indent-{N}`). |
+| `...HTMLAttributes` | — | — | На `<div>`. `role="radiogroup"`. |
+
+### RadioYGroup — `IRadioYGroupProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `...HTMLAttributes` | — | На `<div>`. `role="radiogroup"`. Gap — фиксированный (см. CSS). |
+
+---
+
+## Ключевые особенности реализации
+
+### Native `<input>` + кастомный `<span>` (visually-hidden pattern)
+
+```tsx
+<label>
+    <input type="radio" className={styles.radio} ... />
+    <span className={styles.radioIcon} />
+    {children && <Text>{children}</Text>}
+</label>
+```
+
+- `<input>` скрыт визуально (`appearance: none` / `opacity: 0` в стилях), но **остаётся в фокусной последовательности** и работает как нативный radio.
+- `<span class="radioIcon">` — визуальная рамка/точка, реагирует на состояния `:checked`, `:disabled`, `:focus-visible` через CSS-селекторы вида `input:checked + .radioIcon`.
+
+### Текст-описание — через `<Text size>`
+
+- Маппинг по `size`: SM→B4, MD→B3, LG→B2.
+- Если `children` пуст — `<Text>` не рендерится (избегаем лишнего span).
+- `nonempty` класс на label — позволяет CSS отличать "только иконка" от "иконка + текст" (например, для горизонтального gap'а).
+
+### `labelAttributes` — мерж className
+
+```ts
+labelAttributes?.className → clsx(..., labelAttributes?.className)
+```
+
+- Стандартный паттерн.
+
+### Группы — `role="radiogroup"`, **без `value`**
+
+- `RadioXGroup` / `RadioYGroup` — **тонкие layout-обёртки**. Не управляют выбранным значением, не вешают `name` на дочерние radio. Контракт name/value/onChange — на потребителе.
+- Это отличается от ряда библиотек (`MUI.RadioGroup` управляет состоянием) — здесь группа только семантическая + layout.
+
+### `RadioXGroup.indent` — фиксированный набор
+
+- `TIndentSize = 12 | 16 | 20 | 24 | 28 | 32` (px). Добавляет класс `indent-{N}`.
+- Default `12px`.
+
+---
+
+## Инварианты
+
+- **`<input type="radio">`** — нативный, фиксирован. `type` исключён из props.
+- **`size: EComponentSize` default `MD`** — наш enum, не размер `<input>`.
+- **`children` — описание справа**, опционально. Без `children` рендерится только иконка.
+- **Текст всегда `<Text tag="div" size>` с маппингом** SM→B4 / MD→B3 / LG→B2.
+- **`labelAttributes` — единственный канал** для прокидывания `<label>`-атрибутов (`for`, `id`, `className`).
+- **`RadioXGroup`/`RadioYGroup`** — layout + `role="radiogroup"`. Не управляют состоянием.
+- **`RadioXGroup.indent` default `12`**, набор фиксирован `TIndentSize`.
+- **ForwardRef → `<input>`** на Radio. Не на label/wrapper.
+- **`RadioXGroup` / `RadioYGroup` — `FC`, не forwardRef**.
+- **`data-tx`** — на `<label>`.
+
+---
+
+## Accessibility
+
+- Нативный `<input type="radio">` — клавиатура (стрелки внутри той же `name`-группы), screen readers — работают «из коробки».
+- **`<label>` оборачивает input** — клик по тексту/иконке тоже выбирает radio.
+- `role="radiogroup"` на контейнере группы — корректная семантика для AT. Но **`aria-labelledby`** / `aria-label` группы нужно передавать через `...rest`.
+- **`name`** — потребитель должен передавать одинаковый name на все радио в группе (иначе нативная группировка/стрелки не работают).
+- `disabled` — корректно через `<input disabled>` (focus-skip, SR озвучивает).
+- `:focus-visible` стили — через CSS-класс на `<span class="radioIcon">` (стандартный паттерн).
+
+---
+
+## Дизайн-токены
+
+Нет собственных. Цвета/размер `<span class="radioIcon">` — из `styles/Radio.module.less` (часто переменные проекта; уточнить в LESS).
+
+---
+
+## Связанные компоненты
+
+- `Checkbox` — параллельный компонент.
+- `Text` (Typography) — описание.
+- `RadioXGroup` / `RadioYGroup` — layout-группы.
+- `EComponentSize`, `ETextSize`.
+- `TIndentSize` (`consts/IndentConst`).
+
+---
+
+## Stories
+
+`stories/Radio/Radio.stories.tsx`
+Примеры: `stories/Radio/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |