@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/Portal.md

@@ -1,11 +1,9 @@
 ---
 component: Portal
-category: Utilities
-figma-node: ""
-figma-file: ""
-related: [ModalWindow, LightBox, Dropdown, Tooltip]
+category: Portal
+related: [Dropdown, Tooltip]
 tokens: []
-stories: ""
+stories: stories/Portal/Portal.stories.tsx
 version: "1.0"
 ---
 
@@ -13,107 +11,173 @@ version: "1.0"
 
 ## Назначение
 
-Тонкая обёртка над `ReactDOM.createPortal`. Рендерит `children` во
-внешний DOM-узел (`container`), оставаясь в текущем React-дереве
-(контекст, обработчики, focus-trap работают как обычно).
+Сервисный компонент — тонкая обёртка над `ReactDOM.createPortal`. Рендерит
+`children` в указанный внешний DOM-узел (`container`), а не в месте объявления,
+сохраняя React-контекст и всплытие событий по React-дереву.
 
-Используй когда: нужен node вне родительского дерева (обход
-`overflow: hidden`, `z-index`-стэк, поверх модалок). В большинстве
-случаев напрямую — внутри `ModalWindow`/`Dropdown`/`Tooltip`/`LightBox`.
+Используй когда: содержимое нужно вынести из DOM-иерархии родителя — выйти за
+пределы контейнера с `overflow: hidden`, поверх `z-index`-контекста, в
+`document.body` или произвольный узел (всплывающие слои, тултипы, дропдауны).
 
----
-
-## Файловая структура
-
-```text
-src/components/Portal/
-├── Portal.tsx   # FC, 1 строка — createPortal
-└── index.ts     # Barrel
-```
-
-Нет стилей, тестов, stories.
+Не используй когда:
+- Нужен готовый всплывающий слой с позиционированием и поведением — используй
+  `Dropdown`, `Tooltip`, `ModalWindow`: они уже рендерятся через Portal или
+  собственные механизмы.
+- Контейнер ещё не существует на момент рендера — сначала дождись монтирования
+  узла (создай его через ref-callback/`useState`), затем рендери Portal.
 
 ---
 
 ## Варианты и props
 
-### `IPortalProps`
+### Обязательные props
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `children` | `ReactNode` | Да | Рендерится в `container`. |
-| `container` | `Element \| DocumentFragment` | Да | Целевой DOM-узел. |
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactNode` | Содержимое, рендерящееся в `container` |
+| `container` | `Element \| DocumentFragment` | Существующий DOM-узел, в который рендерится содержимое |
 
-Никаких опциональных props или fallback'ов.
+Опциональных props нет. Компонент не рендерит собственный host-элемент и не
+принимает `className`/rest-атрибуты — стилизуется сам `container` или
+содержимое.
 
----
+### Особенности поведения
 
-## Ключевые особенности реализации
+- При смене `container` на rerender содержимое переносится в новый узел,
+  старый очищается.
+- При unmount содержимое удаляется из `container`; сам узел-контейнер
+  компонент не создаёт и не удаляет — его жизненный цикл на потребителе.
+- События из содержимого всплывают по React-дереву (к родителю Portal), а не
+  по DOM-дереву контейнера — стандартная семантика `createPortal`.
 
-### `ReactDOM.createPortal`
+---
 
-```tsx
-export const Portal = ({ children, container }) => ReactDOM.createPortal(children, container);
-```
+## Дизайн-токены
 
-- React сам управляет mount/unmount через виртуальное дерево.
-- **Контекст-провайдеры**, **events bubbling** работают, как если бы дерево было локальным (events bubble через React-tree, не DOM-tree).
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
 
-### `container` — обязателен
+---
 
-- В отличие от ряда библиотек, `Portal` **не создаёт** контейнер сам и **не подбирает** `document.body` по умолчанию.
-- Потребитель сам решает, куда монтировать (типичный паттерн: создать `<div>` в `document.body` и передать сюда).
+## Инварианты
 
-### **Не SSR-safe**
+- **Без `forwardRef` — осознанное исключение** из общего правила библиотеки:
+  Portal не рендерит собственный host-элемент, ref форвардить некуда. Не
+  добавлять `forwardRef` без изменения контракта.
+- **Имена props `children` и `container`** и тип `container: Element |
+  DocumentFragment` — публичное API с версии 1.21.0, не менять.
+- **Интерфейс `IPortalProps`** экспортируется из barrel — не переименовывать.
+- Реализация остаётся тонкой обёрткой над `ReactDOM.createPortal` (React
+  17-совместимый API) — не добавлять состояние, эффекты и React 18-only API:
+  код синхронизируется в release-0.
 
-- `createPortal` на сервере выбрасывает ошибку. При SSR — потребитель должен оборачивать в `if (typeof window !== "undefined")` или использовать `useEffect`.
-- В этом проекте — обычно через `useEffect` создают и монтируют контейнер (см. `ModalWindow`, `LightBox`).
+---
 
-### **Никаких lifecycle-хуков**
+## Accessibility
 
-- Portal не отслеживает изменение `container`. При смене `container` — React удалит старый child из старого container и смонтирует в новый (стандартное поведение createPortal).
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева.
+- Портал не управляет фокусом: focus trap, возврат фокуса, `aria-modal` и
+  прочие контракты всплывающих слоёв — ответственность потребителя
+  (`ModalWindow`, `Dropdown` реализуют их самостоятельно).
+- Учитывай порядок чтения screen reader'ом: содержимое читается в месте
+  `container` в DOM, а не в месте объявления.
 
 ---
 
-## Инварианты
+## Связанные компоненты
 
-- **`container` — обязателен**, не optional.
-- **`children` — `ReactNode`**, не `ReactElement` (можно массив, fragment, primitive).
-- **`FC`, не `forwardRef`** — ref на children идёт нативно через React-tree, на сам Portal-component — нет.
-- **Не SSR-safe** — потребитель ответственен за условный рендер.
-- **Контейнер не создаётся автоматически** — приходит снаружи.
-- **Никаких side effects** — нет `useEffect`, нет mount-классов, нет cleanup.
+- `Dropdown` (`src/components/Dropdown/`) — рендерит выпадающий слой через
+  Portal в `document.body`.
+- `Tooltip` (`src/components/Tooltip/`) — desktop- и mobile-реализации
+  рендерят тултип через Portal: mobile — всегда в `document.body`, desktop — в
+  `renderContainer ?? document.body`.
 
 ---
 
-## Accessibility
+## Stories
+
+Основные истории: `stories/Portal/Portal.stories.tsx`
+Файлы примеров: `stories/Portal/examples/`
 
-- Portal не влияет на семантику. **Focus management, ARIA-связи** — задача потребителя.
-- Tab-последовательность определяется DOM-порядком: portal'ed узел — там, куда смонтирован, не там, где находится в JSX. Это часто нарушает focus order — нужен focus-trap внутри.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `children`; `container` задаётся обёрткой (узел с пунктирной рамкой) |
+| `Default` | `Default.tsx` | Содержимое рендерится в указанный DOM-узел, а не в месте объявления |
+| `Example` | `Example.tsx` | Типовой сценарий: вынос содержимого из контейнера с `overflow: hidden` |
 
 ---
 
-## Дизайн-токены
+## История изменений
 
-Нет.
+| Дата | Изменение |
+|---|---|
+| 2026-07-29 | Создан документ. AI-рефакторинг (TRI-67): JSDoc на props `IPortalProps`, unit-тесты (5 кейсов: рендер в container/DocumentFragment, rerender, смена container, unmount), stories по modern pattern. Публичный API не менялся; `forwardRef` осознанно отсутствует. |
 
 ---
 
-## Связанные компоненты
+## Примеры использования
 
-- `ModalWindow` / `LightBox` / `Dropdown` / `Tooltip` — все используют Portal.
-- `react-dom` `createPortal` — нативный API.
+### Default
 
----
+`stories/Portal/examples/Default.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { Portal } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <div>Компонент Portal объявлен здесь, но его содержимое рендерится в контейнер с пунктирной рамкой.</div>
+            <div
+                ref={setContainer}
+                style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}
+            />
+            {container && <Portal container={container}>Содержимое, отрендеренное через Portal.</Portal>}
+        </div>
+    );
+};
+```
 
-Нет.
+### Example
 
----
+`stories/Portal/examples/Example.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { Portal } from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <div
+                style={{
+                    border: "1px solid rgb(125, 131, 138)",
+                    borderRadius: "4px",
+                    padding: "16px",
+                    height: "48px",
+                    overflow: "hidden",
+                }}
+            >
+                <div>Контейнер с overflow: hidden и фиксированной высотой.</div>
+                {container && (
+                    <Portal container={container}>
+                        <div>
+                            Это содержимое объявлено внутри контейнера с overflow: hidden, но через Portal отрендерено
+                            во внешний узел с пунктирной рамкой, поэтому не обрезается и видно полностью.
+                        </div>
+                    </Portal>
+                )}
+            </div>
+            <div
+                ref={setContainer}
+                style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}
+            />
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |

package/bundle/components/Row.md

@@ -1,9 +1,7 @@
 ---
 component: Row
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Col, Container]
+related: [Col, Gap]
 tokens: []
 stories: stories/Row/Row.stories.tsx
 version: "1.0"
@@ -13,108 +11,87 @@ version: "1.0"
 
 ## Назначение
 
-Строка grid-системы — `<div>` с горизонтальным flex-wrap layout'ом и
-**отрицательными margin'ами по бокам** для компенсации gutter'ов
-дочерних `Col`. Рекомендованный child — `Col`.
+Строка сетки: flex-контейнер с нижним отступом, предназначенный для использования с колонками `Col` в children. Передаёт размер горизонтального отступа между колонками (`gridHorizontalGap`) в дочерние `Col` через внутренний `RowContext`.
 
-Используй когда: компонуешь форму/контент в колоночной сетке проекта.
-Для нестандартного layout'а — flex/grid-CSS напрямую.
+Используй когда: нужно разместить контент в колоночной сетке — несколько `Col` в одной строке с управляемым горизонтальным отступом между ними и вертикальным отступом между строками.
 
----
-
-## Файловая структура
-
-```text
-src/components/Row/
-├── Row.tsx                  # FC; <div> + flex layout
-├── styles/Row.module.less   # margin -horizontal-gap, padding-bottom
-├── index.ts                 # Barrel
-└── __tests__/
-```
+Не используй когда:
+- Нужен только вертикальный отступ между блоками без колонок — используй `Gap`.
+- Children — не колонки `Col`: компонент рассчитан на связку `Row` → `Col`, отрицательные боковые margin компенсируются padding колонок.
 
 ---
 
 ## Варианты и props
 
-### `IRowProps extends React.HTMLAttributes<HTMLDivElement>`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `paddingBottom` | `boolean` | `true` | Нижний отступ строки. `false` — отключить. |
-| `...HTMLAttributes` | — | — | На корневой `<div>`. |
-
-- `paddingBottom: false` → класс `noPaddingBottom`.
-- **Последняя `Row` в родителе** автоматически получает `padding-bottom: 0` через CSS-селектор `:last-child`.
-
----
+### Обязательные props
 
-## Ключевые особенности реализации
+Обязательных props нет.
 
-### Compensating margins
+### Опциональные props
 
-```less
-.row {
-    display: flex;
-    flex-wrap: wrap;
-    margin-left: -@grid-horizontal-gap;
-    margin-right: -@grid-horizontal-gap;
-    padding-bottom: @row-bottom-padding;
-}
-```
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `paddingBottom` | `boolean` | `true` | Нижний отступ строки (16px). При `false` — отступ убирается. У последней строки (`:last-child`) отступ убирается стилями независимо от значения prop. |
+| `gridHorizontalGap` | `EComponentSize.SM \| EComponentSize.MD` | `EComponentSize.SM` | Размер отступа между колонками: SM — 8px, MD — 12px. Передаётся в дочерние `Col` через `RowContext`. |
 
-- Отрицательные margin компенсируют padding'и `Col`'ов — содержимое крайних колонок выровнено по краю Row.
-- Стандартный bootstrap-style grid pattern.
+Компонент расширяет `React.HTMLAttributes<HTMLDivElement>` — принимает все стандартные атрибуты `<div>` (`className`, `style`, `aria-*`, `data-*` и т.д.).
 
-### `padding-bottom` через CSS, а не inline
+### Ограничения
 
-- LESS-переменная `@row-bottom-padding` определяет величину.
-- `:last-child` — обнуление: серия Row друг под другом не накапливает отступ снизу.
+- `gridHorizontalGap` намеренно сужен до `SM | MD` — остальные значения `EComponentSize` не входят в контракт сетки.
+- Механика gap: `Row` задаёт отрицательные `margin-left`/`margin-right`, а `Col` — соответствующий горизонтальный padding (значение получает из `RowContext`). Управлять gap нужно только через prop на `Row`, а не стилями `Col`.
 
-### `flex-wrap: wrap`
+---
 
-- Колонки с суммарной шириной > 100% переносятся на новую строку (внутри одной Row).
+## Дизайн-токены
 
-### **Только базовый `<div>`**
+Компонент не использует CSS-переменных `--triplex-next-*`. Размеры берутся из LESS-переменных сетки в `src/styles/components/grid.less`:
 
-- Нет `forwardRef`, нет slots, нет компонентного API. Простой layout helper.
+```less
+@row-bottom-padding: 16px
+@grid-horizontal-gap-SM: 8px
+@grid-horizontal-gap-MD: 12px
+```
 
 ---
 
 ## Инварианты
 
-- **`<div>` с `display: flex; flex-wrap: wrap`** — изменение типа layout — breaking.
-- **`paddingBottom: true` default** — большинство строк с отступом.
-- **`:last-child` снимает padding-bottom** — публичное CSS-поведение.
-- **Отрицательные margin'ы** = ожидание дочерних `Col`'ов с padding'ами равными `@grid-horizontal-gap`.
-- **`FC, не forwardRef`**.
-- **Контракт child** — `Col` (на уровне типов не enforced).
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<div>`.
+- **Имена публичного API**: компонент `Row`, интерфейс `IRowProps`, props `paddingBottom`, `gridHorizontalGap` и их дефолты — менять нельзя (breaking change).
+- **Barrel `src/components/Row/index.ts` экспортирует только `./Row`** — `RowContext` остаётся внутренним модулем, в barrel не добавлять.
+- **`RowContext` — внутренний контракт с `Col`**: `Col` читает `gridHorizontalGap` из контекста (`src/components/Col/Col.tsx`). Изменение формы `IRowContext` или дефолтного значения контекста требует синхронного обновления `Col`.
+- **Значение контекста мемоизировано** (`React.useMemo` по `gridHorizontalGap`) — не убирать, иначе все `Col`-потребители будут перерендериваться на каждом рендере `Row`.
+- **Корневой DOM-элемент — `<div>`** без ARIA-роли.
+- **CSS-классы `SM`, `MD`, `noPaddingBottom`** в `Row.module.less` используются в unit-тестах; класс `row` — корневой, тестами не проверяется, но фиксируется visual baseline. `SM`/`MD` — исторически не camelCase, переименование требует синхронного обновления тестов и проверки visual baseline.
+- **`displayName = "Row"`** — проверяется тестом.
 
 ---
 
 ## Accessibility
 
-- Нейтральный `<div>` — без семантики. Если строка несёт смысл (form-row), потребитель добавляет `role` сам.
-
----
-
-## Дизайн-токены
-
-LESS-переменные (через `@import '../../../styles/style'`):
-- `@grid-horizontal-gap` — горизонтальный gap.
-- `@row-bottom-padding` — нижний отступ.
+Компонент не интерактивный: рендерит обычный `<div>` без роли, keyboard navigation и focus management не применимы. Потребитель может передать `role` и `aria-*` атрибуты через spread.
 
 ---
 
 ## Связанные компоненты
 
-- `Col` — колонка, основной child.
-- Прочая grid-система (`Container`) — если есть в проекте.
+- `Col` (`src/components/Col/`) — колонка сетки, единственный ожидаемый тип children. Потребляет `gridHorizontalGap` из `RowContext`.
+- `Gap` (`src/components/Gap/`) — вертикальный отступ-разделитель вне колоночной сетки.
 
 ---
 
 ## Stories
 
-`stories/Row/Row.stories.tsx`
+Основные истории: `stories/Row/Row.stories.tsx`
+Файлы примеров: `stories/Row/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `paddingBottom` и `gridHorizontalGap` |
+| `Default` | `Default.tsx` | Две строки по две колонки, отступ между строками по умолчанию |
+| `GridHorizontalGaps` | `GridHorizontalGaps.tsx` | Отступы между колонками SM (8px) и MD (12px) |
+| `WithoutPaddingBottom` | `WithoutPaddingBottom.tsx` | Строки 1 и 3 с `paddingBottom={false}` в контрасте со строкой 2 с отступом по умолчанию |
 
 ---
 
@@ -122,4 +99,129 @@ LESS-переменные (через `@import '../../../styles/style'`):
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-07-28 | Создан документ. AI-рефакторинг (TRI-71): добавлен `forwardRef`, значение `RowContext` мемоизировано, JSDoc на props и контекст, расширены unit-тесты (ref, проброс gap через контекст); stories переведены на modern pattern (`stories/Row/`), включены визуальные тесты. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Row/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <div style={{ maxWidth: "320px" }}>
+        <Row>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 1, Col 1
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 1, Col 2
+                </div>
+            </Col>
+        </Row>
+        <Row>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 2, Col 1
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 2, Col 2
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
+
+### GridHorizontalGaps
+
+`stories/Row/examples/GridHorizontalGaps.tsx`
+
+```tsx
+import React from "react";
+import { Col, EComponentSize, Row } from "@sberbusiness/triplex-next";
+
+export const GridHorizontalGaps = () => (
+    <div style={{ maxWidth: "320px" }}>
+        <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
+        <Row gridHorizontalGap={EComponentSize.SM}>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>Col 1</div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>Col 2</div>
+            </Col>
+        </Row>
+        <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>MD</div>
+        <Row gridHorizontalGap={EComponentSize.MD}>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>Col 1</div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>Col 2</div>
+            </Col>
+        </Row>
+    </div>
+);
+```
+
+### WithoutPaddingBottom
+
+`stories/Row/examples/WithoutPaddingBottom.tsx`
+
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
+
+export const WithoutPaddingBottom = () => (
+    <div style={{ maxWidth: "320px" }}>
+        <Row paddingBottom={false}>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 1, Col 1
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 1, Col 2
+                </div>
+            </Col>
+        </Row>
+        <Row>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 2, Col 1
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 2, Col 2
+                </div>
+            </Col>
+        </Row>
+        <Row paddingBottom={false}>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 3, Col 1
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    Row 3, Col 2
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
+