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

package/bundle/components/LoaderScreen.md

@@ -0,0 +1,134 @@
+---
+component: LoaderScreen
+category: Feedback
+figma-node: ""
+figma-file: ""
+related: [Loader, Skeleton, LightBox, List]
+tokens: []
+stories: stories/Loaders/LoaderScreen
+version: "1.0"
+---
+
+# LoaderScreen
+
+## Назначение
+
+Контейнер-оверлей, рендерящий `LoaderSmall` или `LoaderMiddle` с полупрозрачным
+бэкдропом — поверх блока/экрана, пока идёт загрузка. Centered по `flexbox`
+внутри относительно расположенного родителя (наружный элемент должен иметь
+`position: relative` или быть самим "экраном").
+
+Используй когда: нужно закрыть контент оверлеем на время загрузки
+(в Island'е, Modal'е, Content-wrapper'е). Для inline-спиннера в кнопке —
+`LoaderSmall` напрямую. Для skeleton-загрузки известной структуры — `Skeleton`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/LoaderScreen/
+├── LoaderScreen.tsx                    # FC, <div> + lоадер
+├── index.ts                            # Barrel
+├── styles/LoaderScreen.module.less
+└── __tests__/LoaderScreen.test.tsx
+```
+
+---
+
+## Варианты и props
+
+### `ILoaderScreenProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `type` | `"small" \| "middle"` | — (обязателен) | Тип лоадера внутри. `small` — LoaderSmall, `middle` — LoaderMiddle. |
+| `theme` | `ELoaderSmallTheme` | `BRAND` | Только для `type="small"`. Игнорируется для `middle`. |
+| `size` | `EComponentSize` | `MD` | Только для `type="small"`. Игнорируется для `middle`. |
+| `className`, `...HTMLDivAttributes` | — | — | Стандартные. |
+
+**`type` — строковый литерал**, не enum. Публичный API. Не смешивать с `ELoaderSmallTheme`.
+
+---
+
+## Ключевые особенности реализации
+
+### Два backdrop-класса по типу
+
+```tsx
+{
+    [styles.loaderSmallBackdrop]: type === "small",
+    [styles.loaderMiddleBackdrop]: type === "middle",
+}
+```
+
+- **`loaderSmallBackdrop`** и **`loaderMiddleBackdrop`** задают разную прозрачность/цвет бэкдропа. Middle обычно более явный (полноценный overlay), Small — лёгкий полупрозрачный.
+
+### Middle обёрнут в дополнительный `<div>`
+
+```tsx
+<div className={styles.loaderMiddleBackground}>
+    <LoaderMiddle />
+</div>
+```
+
+Внутренний `background`-wrapper — для "карточки" вокруг точек LoaderMiddle.
+LoaderSmall — просто инлайн-элемент по центру.
+
+### Игнорирование `theme`/`size` для `type="middle"`
+
+`LoaderMiddle` API-less, так что `theme` и `size` принимаются, но не
+используются при `type === "middle"`. Не выкидывать их — потребители
+могут переключать `type` динамически без очистки props.
+
+### Не forwardRef
+
+Компонент — `React.FC`, не `forwardRef`. Это отступление от общего правила
+библиотеки (`forwardRef обязателен`). Известный legacy-момент; для нового
+API-использования нужен ref — оборачивай снаружи.
+
+---
+
+## Инварианты
+
+- **`type: "small" | "middle"`** — строковый литерал. Не заменять на enum без breaking-change.
+- **`theme` / `size` применяются только при `type="small"`** — не разворачивать на `middle` без изменения Loader.
+- **`FC`, без forwardRef** — технический долг. Исправлять — breaking (меняется тип).
+- **Centered через flex внутри оверлея** — родитель должен иметь `position: relative` (или LoaderScreen должен использоваться на фоне самостоятельного блока).
+- **Бэкдроп встроен в LoaderScreen** — отдельно менять прозрачность нельзя, только переопределением CSS-переменной/через `className`.
+
+---
+
+## Accessibility
+
+- `role="status"` и `aria-label="loading"` приходят от вложенных `LoaderSmall`/`LoaderMiddle` — LoaderScreen сам ARIA-атрибутов не добавляет.
+- `<div>`-оверлей **не блокирует клики** по контенту под ним — потребитель должен либо расположить LoaderScreen над блоком с `pointer-events`, либо использовать его в модалках/LightBox, где фокус и клики уже контролируются.
+- Для правильной семантики при глобальной загрузке — ставь `aria-busy="true"` на родительский контейнер.
+
+---
+
+## Дизайн-токены
+
+Нет публичных переменных — цвета бэкдропа в `styles/LoaderScreen.module.less`.
+
+---
+
+## Связанные компоненты
+
+- `Loader` (`LoaderSmall`, `LoaderMiddle`) — вложенные компоненты.
+- `ELoaderSmallTheme`, `EComponentSize` — enum'ы пропсов.
+- `List`, `LightBox`, `ModalWindow` — типовые потребители (оверлей над контентом).
+
+---
+
+## Stories
+
+`stories/Loaders/LoaderScreen/` — stories для обоих типов.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Marker.md

@@ -0,0 +1,127 @@
+---
+component: Marker
+category: Feedback
+figma-node: ""
+figma-file: ""
+related: [MarkerStatus, Badge, TagColor]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Marker
+
+## Назначение
+
+Тонкая обёртка над `Badge.Dot` — цветной кружок-статус (success/error/
+warning/waiting). Содержательно это **именованный preset цвета** для точки,
+чтобы не передавать `palette`-атрибут каждый раз.
+
+Используй когда: нужен компактный индикатор статуса (в строке таблицы,
+заголовке, рядом с меткой) и выбор из фиксированной 4-статусной палитры
+семантики. Для статуса с подписью — `MarkerStatus`. Для кастомного цвета —
+`Badge.Dot` напрямую.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Marker/
+├── Marker.tsx                   # FC, обёртка над Badge.Dot
+├── enums.ts                     # EMarkerStatus (SUCCESS/ERROR/WARNING/WAITING)
+├── utils.ts                     # statusToClassNameMap — публичная, используется MarkerStatus
+├── styles/Marker.module.less    # Цвета статусов
+└── index.ts                     # Barrel
+```
+
+---
+
+## Варианты и props
+
+### `IMarkerProps extends IBadgeDotProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `status` | `EMarkerStatus` | Да | Семантический статус (цвет). |
+| `...IBadgeDotProps` | — | — | Все props `Badge.Dot` (size, className, прочие). |
+
+### EMarkerStatus
+
+```ts
+enum EMarkerStatus {
+    SUCCESS = "success",
+    ERROR = "error",
+    WARNING = "warning",
+    WAITING = "waiting",
+}
+```
+
+Четыре фиксированных статуса. Расширение — breaking change.
+
+---
+
+## Ключевые особенности реализации
+
+### Реализация — одна строка
+
+```tsx
+<Badge.Dot className={clsx(styles.marker, statusToClassNameMap[status], className)} {...rest} />
+```
+
+- Поверх `Badge.Dot` накладывается класс `.marker` + один из `.success/.error/.warning/.waiting` из `Marker.module.less`, которые переопределяют цвета у точки.
+- Все остальные props `Badge.Dot` (включая `size`, `style`) прокидываются как есть.
+
+### `statusToClassNameMap` — экспортируемая утилита
+
+```ts
+export const statusToClassNameMap = { [EMarkerStatus.SUCCESS]: styles.success, ... };
+```
+
+- **Экспортируется для переиспользования в `MarkerStatus`** (который применяет те же классы к своему контейнеру для окраски текста/описания).
+- Если добавляешь статус — обязательно обнови `utils.ts` и LESS-стили, и проверь, что `MarkerStatus` тоже подтягивает новый класс.
+
+---
+
+## Инварианты
+
+- **`EMarkerStatus`** (4 значения) — публичный API. Расширение — breaking.
+- **`Marker = Badge.Dot + className`** — тонкая обёртка; избегать добавления своих props, которые размажут семантику со `Badge`.
+- **`statusToClassNameMap`** экспортируется из `utils.ts` — `MarkerStatus` зависит от неё. Не менять shape.
+- **`size` приходит от `Badge.Dot`** (через `IBadgeDotProps`), а не кастомизируется Marker'ом.
+- **FC, не forwardRef** — ref прокидывается `Badge.Dot` внутри? Проверь перед изменением.
+
+---
+
+## Accessibility
+
+- `Badge.Dot` по умолчанию — декоративный элемент без ARIA. Для анонсирования статуса скринридером потребитель должен добавить `aria-label` через `...rest` или сопроводить текстом рядом.
+- `MarkerStatus` уже выводит текстовый статус — там a11y закрыт.
+
+---
+
+## Дизайн-токены
+
+Цвета статусов заданы в `styles/Marker.module.less` (не через CSS-переменные). Для новой темы статусов — переопределяй в LESS.
+
+---
+
+## Связанные компоненты
+
+- `Badge` / `Badge.Dot` — основа.
+- `MarkerStatus` — Marker + текст + описание, использует тот же `statusToClassNameMap`.
+- `TagColor` — альтернатива для статуса с подписью внутри "пилюли".
+
+---
+
+## Stories
+
+Нет отдельных — только через `MarkerStatus.stories.tsx` (там показаны все 4 статуса).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/MarkerStatus.md

@@ -0,0 +1,148 @@
+---
+component: MarkerStatus
+category: Feedback
+figma-node: ""
+figma-file: ""
+related: [Marker, Badge, Typography]
+tokens: []
+stories: stories/MarkerStatus/MarkerStatus.stories.tsx
+version: "1.0"
+---
+
+# MarkerStatus
+
+## Назначение
+
+Статус-блок: цветная точка (`Marker`) + заголовок (`children`) + опциональное
+описание. Окрашивает **текст заголовка/описания** цветом статуса через
+общий `statusToClassNameMap` (из `Marker/utils`). Два размера — MD / LG.
+
+Используй когда: нужна компактная семантическая индикация состояния с
+подписью (успех операции, ошибка, pending). Для просто точки без текста —
+`Marker`. Для статуса-пилюли с фоном — `TagColor`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/MarkerStatus/
+├── MarkerStatus.tsx                 # FC, div + Marker + Text/Caption
+├── index.ts                         # Barrel
+├── styles/MarkerStatus.module.less  # Цвета текста по статусу, размерные варианты
+└── __tests__/MarkerStatus.test.tsx
+```
+
+---
+
+## Варианты и props
+
+### `IMarkerStatusProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `status` | `EMarkerStatus` (`SUCCESS`/`ERROR`/`WARNING`/`WAITING`) | — | Обязателен. Цвет точки и текста. |
+| `children` | `ReactNode` | — | Заголовок (основной текст статуса). Рендерится в `Text size=B4` (MD) / `B3` (LG). |
+| `description` | `ReactNode` | — | Доп. описание под заголовком. MD — `Caption C1 SECONDARY`; LG — `Text B4 SECONDARY`. |
+| `size` | `EComponentSize.MD \| EComponentSize.LG` | `MD` | **Ограниченный enum-subset** — нет `SM`. |
+
+---
+
+## Ключевые особенности реализации
+
+### Размер = `EComponentSize.MD | EComponentSize.LG`
+
+```ts
+size?: EComponentSize.MD | EComponentSize.LG;
+```
+
+- **SM запрещён на уровне типа**. Если передать `SM` — TS ошибка. Для runtime-значения — визуал не определён.
+- Если появится требование SM — добавить маппинги `sizeToClassNameMap`, `markerStatusSizeToTextSizeMap` и LESS-стиль.
+
+### `size` пробрасывается в `Marker` (Badge.Dot)
+
+```tsx
+<Marker status={status} size={size} />
+```
+
+- Marker получает `size` через `...IBadgeDotProps` — `Badge.Dot` сам определяет, как размер влияет на диаметр точки.
+
+### Маппинг размера → typography-размер
+
+```ts
+const markerStatusSizeToTextSizeMap = {
+    [EComponentSize.MD]: ETextSize.B4,
+    [EComponentSize.LG]: ETextSize.B3,
+};
+```
+
+- MD → B4, LG → B3. Публичный контракт (визуальная спецификация).
+
+### `description` — разный компонент по размеру
+
+```tsx
+size === EComponentSize.MD
+    ? <Caption size={C1} type={SECONDARY}>{description}</Caption>
+    : <Text size={B4} type={SECONDARY}>{description}</Text>
+```
+
+- **MD → Caption (C1)**, **LG → Text (B4 SECONDARY)**. Меньшая строка (Caption) в меньшем размере.
+- `type=SECONDARY` — приглушённый цвет.
+
+### Цвет текста — через `statusToClassNameMap` из Marker/utils
+
+```tsx
+<div className={clsx(styles.markerStatus, sizeToClassNameMap[size], statusToClassNameMap[status], className)}>
+```
+
+- **Переиспользование** CSS-Modules класса из `Marker/styles` — заложена **кросс-файловая зависимость**: `Marker/utils.ts` импортирует `Marker.module.less`. Если стили MarkerStatus переопределяют цвет текста, то они опираются на то, что корневой класс `.success/.error/...` уже задан.
+
+---
+
+## Инварианты
+
+- **`status` обязателен** — без него семантика теряется.
+- **`size: MD | LG`** — тип-ограниченный subset `EComponentSize`. Расширение — breaking для потребителей, проверяющих тип.
+- **Маппинг размера → typography** (B4/B3 для заголовка; C1/B4 для описания) — зафиксирован в коде, публичная визуальная спецификация.
+- **Использует `Marker/utils.statusToClassNameMap`** — изменение shape в Marker сломает MarkerStatus.
+- **FC, не forwardRef** — ref вовне не прокидывается. Legacy.
+- **`data-tx={npm_package_version}`** — маркер версии. Сохранять.
+
+---
+
+## Accessibility
+
+- `<div>` — без ARIA-роли. Статус должен читаться скринридером через **текст в children**. Не полагайся только на цвет.
+- Если children тоже визуально отражает статус (например, "Ошибка"), и нужна дополнительная семантика — добавь `role="status"` через `...rest` или оборачивай MarkerStatus в live region.
+- Цвет текста — только как визуальный акцент. WCAG-контраст контролируется токенами `SECONDARY`/статус-цветами; при кастомных темах — проверить.
+
+---
+
+## Дизайн-токены
+
+Нет публичных переменных компонента; цвета текста статусов заданы в
+`styles/MarkerStatus.module.less`. Цвет точки — через `Marker`.
+
+---
+
+## Связанные компоненты
+
+- `Marker` — цветная точка; то же `EMarkerStatus` и `statusToClassNameMap`.
+- `Badge.Dot` — база для Marker.
+- `Typography` (`Text`, `Caption`) — для заголовка и описания.
+- `TagColor` — альтернатива с фоном-пилюлей.
+
+---
+
+## Stories
+
+`stories/MarkerStatus/MarkerStatus.stories.tsx`
+Примеры: `stories/MarkerStatus/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/MediaWidth.md

@@ -0,0 +1,169 @@
+---
+component: MediaWidth
+category: Utilities
+figma-node: ""
+figma-file: ""
+related: [MobileView, IslandWidget]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# MediaWidth
+
+## Назначение
+
+Набор компонентов + хук для условного рендеринга по ширине окна:
+- **`useMatchMedia(query, initial)`** — хук, обёртка над `window.matchMedia` с live-обновлением через `change`-listener.
+- **`MediaMinWidth` / `MediaMaxWidth` / `MediaBetweenWidth`** — рендерят `children` / `fallback` по результату media-query.
+- **`MediaWidth`** — универсальная обёртка; по наличию `minWidth`/`maxWidth` выбирает нужный из трёх.
+
+Используй когда: нужно рендерить разный UI на разных брейкпоинтах.
+Для бинарного "mobile vs desktop" — `MobileView`. Для стилей — CSS `@media`
+напрямую (без JS-условия).
+
+---
+
+## Файловая структура
+
+```text
+src/components/MediaWidth/
+├── MediaWidth.tsx            # Компонент-диспетчер
+├── MediaMinWidth.tsx         # min-width only
+├── MediaMaxWidth.tsx         # max-width only
+├── MediaBetweenWidth.tsx     # between min and max
+├── useMatchMedia.ts          # Хук
+├── index.ts                  # Barrel (все 4 компонента + хук)
+└── __tests__/
+```
+
+---
+
+## Варианты и props
+
+### MediaWidth — `IMediaProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `children` | `ReactElement \| null` | Да | Элемент рендерится при совпадении с media-query. |
+| `fallback` | `ReactElement \| null` | Да | Рендерится, если не совпало. |
+| `minWidth` | `EScreenWidth` | Нет | Нижняя граница. |
+| `maxWidth` | `EScreenWidth` | Нет | Верхняя граница. |
+
+Логика выбора:
+- `minWidth && maxWidth` → `MediaBetweenWidth`
+- `minWidth` → `MediaMinWidth`
+- `maxWidth` → `MediaMaxWidth`
+- Ни один — возвращает `fallback`.
+
+### MediaMinWidth / MediaMaxWidth / MediaBetweenWidth
+
+Аналогичные props (`children`, `fallback`, соответствующие `min`/`max`).
+
+### useMatchMedia — `(query: string, initial: boolean) => boolean`
+
+| Параметр | Описание |
+|---|---|
+| `query` | Полный media-query (например, `"(max-width: 767px)"`). |
+| `initial` | Начальное значение до первого рендера — критично для SSR/первого кадра. |
+
+Возвращает `true`, если query совпадает. Подписывается на `change`, возвращает актуальное значение.
+
+### EScreenWidth (из `@sberbusiness/triplex-next/helpers/breakpoints`)
+
+Breakpoint-значения: `XS_MAX`, `SM_MIN`, `SM_MAX`, `MD_MIN`, `MD_MAX`, `LG_MIN`, `LG_MAX`, `XL_MIN`, и т.д. (строковые — в px). Используются как значения `minWidth`/`maxWidth`.
+
+---
+
+## Ключевые особенности реализации
+
+### `children` / `fallback` обязательны — нет "пустого рендера"
+
+```ts
+children: React.ReactElement | null;
+fallback: React.ReactElement | null;
+```
+
+- Оба slot'а должны быть заданы (даже если один — `null`). Не `children?: ReactNode`.
+- **Render-props стиль "if/else"**, не "return null if mismatch".
+
+### `window.innerWidth` на первом рендере — НЕ SSR-safe
+
+```ts
+useMatchMedia(`(min-width: ${minWidth})`, window.innerWidth >= parseInt(minWidth));
+```
+
+- `window.innerWidth` в initial-аргументе выполняется **при рендере**, не в `useEffect` — упадёт на SSR.
+- Потребители в SSR должны оборачивать в ClientOnly или подавать `false`/`true` безопасный default через свой wrapper.
+
+### `useMatchMedia` — `addEventListener("change")`, не deprecated `addListener`
+
+```ts
+mediaQueryList.addEventListener("change", handleChangeMatches);
+```
+
+- Современный API. Safari 13.1+, Chrome 76+ — ок.
+- **Legacy `addListener` не используется** — если нужна поддержка старых Safari, нужен polyfill.
+
+### `useEffect` зависит только от `query`
+
+Колбэк `handleChangeMatches` всегда зовёт `setMatches(event.matches)` — `initial` игнорируется после первого рендера.
+
+### `MediaBetweenWidth` query — AND двух conditions
+
+```ts
+`(max-width: ${maxWidth}) and (min-width: ${minWidth})`
+```
+
+Оба условия должны выполняться. `between` — это **пересечение**.
+
+### `MediaWidth` — не "матчит всё" по умолчанию
+
+Если ни `minWidth`, ни `maxWidth` не переданы — возвращает `fallback`. Это неочевидно: потребители могут ожидать, что пустая media-query рендерит `children`. Потому всегда **передавай хотя бы одну границу**.
+
+---
+
+## Инварианты
+
+- **`children` и `fallback` — обязательные `ReactElement | null`**, не `ReactNode`. Не менять на optional.
+- **`EScreenWidth` как тип `minWidth`/`maxWidth`** — потребители завязаны на брейкпоинты библиотеки; произвольные строки не принимаются.
+- **`useMatchMedia(initial)` аргумент обязателен** — отсутствие initial ломает SSR-совместимость (которая и так условная).
+- **`window.innerWidth` в initial** — legacy-approach. Не вставлять в SSR-контекст без защиты.
+- **`addEventListener("change")`** — современный API; не переключать на deprecated `addListener`.
+- **`MediaWidth` без границ → `fallback`** — документированное поведение, не менять.
+
+---
+
+## Accessibility
+
+- JS-условный рендеринг → **содержимое DOM меняется на брейкпоинте**. При переключении фокуса/viewport/скринридера это может вызвать нежелательный повторный анонс.
+- Предпочитай CSS `@media` + `display: none` там, где возможно: DOM стабилен, скринридеры видят весь контент (если это желаемое поведение) или выбираешь, какой показать через `aria-hidden`.
+- Используй `MediaWidth`/`MobileView` только тогда, когда действительно нужно **разное дерево React'а** (разные компоненты, не CSS-вариации).
+
+---
+
+## Дизайн-токены
+
+Нет. Брейкпоинты — `EScreenWidth` (строковые px).
+
+---
+
+## Связанные компоненты
+
+- `MobileView` — частный случай (mobile vs desktop), use-case определён.
+- `IslandWidget` — использует `useMatchMedia` для адаптивного сворачивания.
+- `helpers/breakpoints.EScreenWidth` — источник брейкпоинтов.
+
+---
+
+## Stories
+
+Нет. Компонент утилитарный; покрытие в тестах и через потребителей.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |