@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.45.0-beta

package/bundle/components/ListSortableItem.md

@@ -3,10 +3,10 @@ component: ListSortableItem
 category: List
 related: [ListSortable, ListSortableItemTarget, ListSortableItemControls, ListItem]
 tokens:
-  - --triplex-next-ListItem-Background
-  - --triplex-next-ListItem-Background_Selected
-  - --triplex-next-ListItem-Background_Dragging
-  - --triplex-next-ListItem-Shadow_Dragging
+  - ListItem.Background
+  - ListItem.Background_Hover
+  - ListItem.Background_Dragging
+  - ListItem.Shadow_Dragging
 stories: stories/List/List.stories.tsx
 version: "1.0"
 ---
@@ -54,14 +54,17 @@ drag-handle нужно вынести в отдельный элемент.
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/ListItem.ts`.
+
 Сам `ListSortableItem` не использует токены (только z-index при `dragging`).
 Токены применяются в `ListSortableItem.Target`:
 
 ```text
---triplex-next-ListItem-Background           // фон по умолчанию
---triplex-next-ListItem-Background_Selected  // фон при hover
---triplex-next-ListItem-Background_Dragging  // фон во время drag
---triplex-next-ListItem-Shadow_Dragging      // тень во время drag
+ListItem.Background           // фон по умолчанию
+ListItem.Background_Hover     // фон при hover
+ListItem.Background_Dragging  // фон во время drag
+ListItem.Shadow_Dragging      // тень во время drag
 ```
 
 ---

package/bundle/components/ListTableItem.md

@@ -3,8 +3,8 @@ component: ListTableItem
 category: List
 related: [ListItem, ListItemSelectable, ListItemControls, ListItemControlsButton, SwipeableArea]
 tokens:
-  - --triplex-next-ListItem-Background
-  - --triplex-next-ListItem-Background_Selected
+  - ListItem.Background
+  - ListItem.Background_Selected
 stories: stories/List/ListTableItem.stories.tsx
 version: "1.0"
 ---
@@ -50,9 +50,12 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/ListItem.ts`.
+
 ```text
---triplex-next-ListItem-Background          // фон строки
---triplex-next-ListItem-Background_Selected // фон выбранной строки (через ListItemSelectable + ListItemContent)
+ListItem.Background          // фон строки
+ListItem.Background_Selected // фон выбранной строки (через ListItemSelectable + ListItemContent)
 ```
 
 Применяются в подкомпонентах `ListItemContent`/`ListItemSelectable`. Сам

package/bundle/components/LoaderMiddle.md

@@ -3,8 +3,8 @@ component: LoaderMiddle
 category: Loaders
 related: [LoaderSmall, LoaderScreen, TableBasic]
 tokens:
-  - --triplex-next-Loader-Middle_Background_Default
-  - --triplex-next-Loader-Element_Background_Brand
+  - Loader.Middle_Background_Default
+  - Loader.Element_Background_Brand
 stories: stories/Loaders/LoaderMiddle/LoaderMiddle.stories.tsx
 version: "1.0"
 ---
@@ -48,9 +48,12 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Loader.ts`.
+
 ```text
---triplex-next-Loader-Middle_Background_Default
---triplex-next-Loader-Element_Background_Brand
+Loader.Middle_Background_Default
+Loader.Element_Background_Brand
 ```
 
 - `Middle_Background_Default` — фон квадратной подложки (`ColorNeutral.80` в светлой теме,

package/bundle/components/LoaderScreen.md

@@ -3,8 +3,8 @@ component: LoaderScreen
 category: Loaders
 related: [LoaderSmall, LoaderMiddle, Gap, Text, ModalWindowContent, LightBoxContent, LightBoxSideOverlay, List, TableBasic, MultiselectField]
 tokens:
-  - --triplex-next-LoaderScreen-Small_Backdrop_Default
-  - --triplex-next-LoaderScreen-Middle_Backdrop_Default
+  - LoaderScreen.Small_Backdrop_Default
+  - LoaderScreen.Middle_Backdrop_Default
 stories: stories/Loaders/LoaderScreen/LoaderScreen.stories.tsx
 version: "1.0"
 ---
@@ -85,19 +85,22 @@ LoaderScreen и сами фиксируют `type="middle"`. Потребите
 
 ## Дизайн-токены
 
-```
---triplex-next-LoaderScreen-Small_Backdrop_Default    (подложка при type="small")
---triplex-next-LoaderScreen-Middle_Backdrop_Default   (подложка при type="middle")
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/LoaderScreen.ts`.
+
+```text
+LoaderScreen.Small_Backdrop_Default    (подложка при type="small")
+LoaderScreen.Middle_Backdrop_Default   (подложка при type="middle")
 ```
 
 Определены в `src/components/DesignTokens/components/LoaderScreen.ts`. Оба ссылаются на
 `ColorNeutralAlpha.30` (в тёмной теме — `ColorDarkNeutralAlpha.30`), то есть визуально совпадают, но
 разведены по типам намеренно — чтобы дизайн мог развести их независимо.
 
-Там же объявлен третий токен `--triplex-next-LoaderScreen-Middle_Background_Default`, который стилями
+Там же объявлен третий токен `LoaderScreen.Middle_Background_Default`, который стилями
 LoaderScreen **не используется**: фон плашки `LoaderMiddle` берётся из
-`--triplex-next-Loader-Middle_Background_Default`, а точки — из
-`--triplex-next-Loader-Element_Background_Brand`. Токен остаётся в публичном наборе (его удаление —
+`Loader.Middle_Background_Default`, а точки — из
+`Loader.Element_Background_Brand`. Токен остаётся в публичном наборе (его удаление —
 breaking change для темизации), но опираться на него не нужно.
 
 Собственных цветов текста у компонента нет — они приходят из `Text` (`Typography`).

package/bundle/components/LoaderSmall.md

@@ -3,8 +3,8 @@ component: LoaderSmall
 category: Loaders
 related: [LoaderMiddle, LoaderScreen, Button, Dropdown, ListItemLoading, SuggestField, SelectExtendedField]
 tokens:
-  - --triplex-next-Loader-Element_Background_Brand
-  - --triplex-next-Loader-Element_Background_Neutral
+  - Loader.Element_Background_Brand
+  - Loader.Element_Background_Neutral
 stories: stories/Loaders/LoaderSmall/LoaderSmall.stories.tsx
 version: "1.0"
 ---
@@ -62,9 +62,12 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Loader.ts`.
+
 ```text
---triplex-next-Loader-Element_Background_Brand
---triplex-next-Loader-Element_Background_Neutral
+Loader.Element_Background_Brand
+Loader.Element_Background_Neutral
 ```
 
 - `Element_Background_Brand` — цвет точек темы `BRAND` (`ColorBrand.50` в обеих темах).

package/bundle/components/Marker.md

@@ -1,11 +1,13 @@
 ---
 component: Marker
-category: Feedback
-figma-node: ""
-figma-file: ""
-related: [MarkerStatus, Badge, TagColor]
-tokens: []
-stories: ""
+category: Marker
+related: [Badge, MarkerStatus]
+tokens:
+  - Marker.Background_Error
+  - Marker.Background_Success
+  - Marker.Background_Waiting
+  - Marker.Background_Warning
+stories: stories/Marker/Marker.stories.tsx
 version: "1.0"
 ---
 
@@ -13,110 +15,150 @@ version: "1.0"
 
 ## Назначение
 
-Тонкая обёртка над `Badge.Dot` — цветной кружок-статус (success/error/
-warning/waiting). Содержательно это **именованный preset цвета** для точки,
-чтобы не передавать `palette`-атрибут каждый раз.
+Цветная точка-индикатор статуса. Тонкая обёртка над `Badge.Dot`: единственное, что
+`Marker` добавляет к точке, — цвет фона по статусу. Ни содержимого, ни состояния, ни
+логики у компонента нет; размер, разметка и проброс `ref` целиком приходят из `Badge.Dot`.
 
-Используй когда: нужен компактный индикатор статуса (в строке таблицы,
-заголовке, рядом с меткой) и выбор из фиксированной 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
-```
+- Нужна точка с подписью статуса и описанием под ней — возьми `MarkerStatus`, это
+  готовая композиция `Marker` + типографика.
+- Нужен нейтральный индикатор без статусной семантики (счётчик уведомлений,
+  «есть непрочитанное») — возьми `Badge.Dot` напрямую: у него один общий токен фона.
+- Нужен интерактивный элемент — `Marker` рендерит неинтерактивный `<span>` без роли,
+  фокуса и обработки клавиатуры.
 
 ---
 
 ## Варианты и props
 
-### `IMarkerProps extends IBadgeDotProps`
+`IMarkerProps extends IBadgeDotProps`, то есть публичный API `Marker` наследует форму
+props точки: любой стандартный атрибут `<span>` (`id`, `data-*`, `style`, `role`,
+`aria-*`, обработчики) уходит на корневой элемент через `...restProps`. `className`
+объединяется с базовыми классами через `clsx`, а не заменяет их.
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `status` | `EMarkerStatus` | Да | Семантический статус (цвет). |
-| `...IBadgeDotProps` | — | — | Все props `Badge.Dot` (size, className, прочие). |
+### Обязательные props
 
-### EMarkerStatus
+| Prop | Тип | Описание |
+|---|---|---|
+| `status` | `EMarkerStatus` | Цвет точки: `SUCCESS` / `ERROR` / `WARNING` / `WAITING`. Значения по умолчанию нет |
+| `size` | `EComponentSize` | Диаметр точки: `SM` — 6px, `MD` — 8px, `LG` — 10px. Приходит из `IBadgeDotProps`, значения по умолчанию нет |
 
-```ts
-enum EMarkerStatus {
-    SUCCESS = "success",
-    ERROR = "error",
-    WARNING = "warning",
-    WAITING = "waiting",
-}
-```
+Опциональных props сверх стандартных атрибутов `<span>` у компонента нет.
+`children` унаследован из `IBadgeDotProps` как `never` — точка не имеет содержимого,
+передать детей не даст типизация.
 
-Четыре фиксированных статуса. Расширение — breaking change.
+### Статусы и цвета
 
----
+Каждому значению `EMarkerStatus` соответствует один css-класс и один токен фона —
+соответствие задано таблицей `STATUS_TO_CLASS_NAME_MAP` в `src/components/Marker/utils.ts`.
+Другой палитры и других вариантов оформления у компонента нет: чтобы добавить статус,
+нужно добавить и значение enum (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` — экспортируемая утилита
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Marker.ts`.
 
-```ts
-export const statusToClassNameMap = { [EMarkerStatus.SUCCESS]: styles.success, ... };
+```text
+Marker.Background_Success
+Marker.Background_Error
+Marker.Background_Warning
+Marker.Background_Waiting
 ```
 
-- **Экспортируется для переиспользования в `MarkerStatus`** (который применяет те же классы к своему контейнеру для окраски текста/описания).
-- Если добавляешь статус — обязательно обнови `utils.ts` и LESS-стили, и проверь, что `MarkerStatus` тоже подтягивает новый класс.
+Значения одинаковы в светлой и тёмной темах: `ColorBrand.50`, `ColorError.50`,
+`ColorWarning.50`, `ColorSystem.50` соответственно. Геометрия точки (диаметр,
+скругление) токенами не задаётся — она приходит из `Badge.Dot` литералами в LESS.
 
 ---
 
 ## Инварианты
 
-- **`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` внутри? Проверь перед изменением.
+- **`forwardRef` — не убирать.** `ref` уходит на корневой `<span>`, отрендеренный
+  `Badge.Dot` (тип — `HTMLSpanElement`).
+- **Корневой элемент — `<span>` из `Badge.Dot`.** Собственной разметки `Marker` не
+  создаёт; смена тега или добавление обёртки ломает инлайновое размещение и вертикальное
+  выравнивание у потребителей (в том числе у `MarkerStatus`).
+- **Значения `EMarkerStatus`** (`"success"`, `"error"`, `"warning"`, `"waiting"`) —
+  часть публичного API. Совпадают с именами css-классов в `Marker.module.less`, но это
+  совпадение, а не контракт: связь между статусом и классом идёт только через
+  `STATUS_TO_CLASS_NAME_MAP`.
+- **`STATUS_TO_CLASS_NAME_MAP` — внутренняя утилита, но с внешним потребителем.**
+  Через barrel не экспортируется, однако `MarkerStatus` импортирует её напрямую
+  (`src/components/MarkerStatus/MarkerStatus.tsx`) и вешает те же классы на свой
+  корневой `<div>`; на них опирается `MarkerStatus.test.tsx`. Переименование карты
+  или её ключей ломает соседний компонент и его тест.
+- **Классы `.success` / `.error` / `.warning` / `.waiting` работают только вложенными
+  в `.marker`** (в LESS они записаны как `&.success` и т.д.). На корневом элементе
+  `MarkerStatus` те же классы фона не дают — там они висят как маркер статуса для тестов.
+- **`IMarkerProps extends IBadgeDotProps`** — любое изменение формы `IBadgeDotProps`
+  автоматически меняет публичный API `Marker`.
+- **`displayName`** — `Marker`, виден в React DevTools.
+- **Имена токенов `Marker.Background_Success` / `_Error` / `_Warning` / `_Waiting`** —
+  не переименовывать: путь токена потребитель передаёт в `ThemeProvider`, а на
+  соответствующий ему внутренний css-слой ссылается `Marker.module.less`.
 
 ---
 
 ## Accessibility
 
-- `Badge.Dot` по умолчанию — декоративный элемент без ARIA. Для анонсирования статуса скринридером потребитель должен добавить `aria-label` через `...rest` или сопроводить текстом рядом.
-- `MarkerStatus` уже выводит текстовый статус — там a11y закрыт.
+Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру, ARIA-ролей и
+атрибутов сам не выставляет. Строк на конкретном языке не хардкодит — весь текст
+приходит от потребителя.
 
----
+**Своего доступного имени у точки нет** — это ограничение унаследовано от `Badge.Dot`:
+корневой `<span>` без роли попадает в `generic`, а для него доступное имя запрещено,
+поэтому одного `aria-label` недостаточно. Обязанность потребителя:
 
-## Дизайн-токены
+- если статус продублирован видимым текстом рядом (типичный случай — `MarkerStatus`),
+  точка декоративна: передай `aria-hidden`;
+- если точка — единственный носитель смысла, передай роль, поддерживающую имя, вместе
+  с текстом: `role="img"` и `aria-label` (оба уходят в `...restProps`).
 
-Цвета статусов заданы в `styles/Marker.module.less` (не через CSS-переменные). Для новой темы статусов — переопределяй в LESS.
+**Пример внутри библиотеки:** `MarkerStatus` рендерит `<Marker status={status} size={size} />`
+без `aria-hidden` — осознанно: смысл статуса там несёт текст рядом, а точка без роли
+попадает в `generic` и своего имени в дерево доступности не добавляет
+(см. `MarkerStatus-ai.md` → «Accessibility»). Для отдельно стоящего `Marker` это
+не образец: там носитель смысла один, и роль с именем нужны.
 
 ---
 
 ## Связанные компоненты
 
-- `Badge` / `Badge.Dot` — основа.
-- `MarkerStatus` — Marker + текст + описание, использует тот же `statusToClassNameMap`.
-- `TagColor` — альтернатива для статуса с подписью внутри "пилюли".
+- `Badge` (`src/components/Badge/Badge.tsx`) — семейство, из которого `Marker` берёт
+  точку: рендерит `Badge.Dot` и наследует `IBadgeDotProps`. Всё, кроме цвета фона
+  (размеры, разметка, `ref`, ограничение `children: never`), задаётся там.
+- `MarkerStatus` (`src/components/MarkerStatus/MarkerStatus.tsx`) — готовая композиция
+  «точка + заголовок статуса + описание». Единственный внутренний потребитель `Marker`,
+  и при этом он опирается на внутреннюю карту `STATUS_TO_CLASS_NAME_MAP` — см. «Инварианты».
 
 ---
 
 ## Stories
 
-Нет отдельных — только через `MarkerStatus.stories.tsx` (там показаны все 4 статуса).
+Основные истории: `stories/Marker/Marker.stories.tsx`
+Файлы примеров: `stories/Marker/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный подбор `status` и `size` |
+| `Default` | `Default.tsx` | Минимальный вызов: оба props обязательны |
+| `Statuses` | `Statuses.tsx` | Все четыре статуса с подписями |
+| `Sizes` | `Sizes.tsx` | Размеры `SM` / `MD` / `LG` |
+| `WithAccessibleName` | `WithAccessibleName.tsx` | Точка как единственный носитель смысла: `role="img"` + `aria-label` |
+
+Скриншот-регрессия снимается со стори `Statuses` и `Sizes`
+(`__screenshots__/marker--{statuses,sizes}--xs|xl.png`). `Playground` исключён как
+интерактивная песочница, `Default` и `WithAccessibleName` — через `testRunner: { skip: true }`:
+обе рендерят ровно ту же точку, что уже есть в `Statuses`. Отдельная стори `VisualTests`
+не нужна — у компонента нет состояний, требующих взаимодействия (ни hover, ни focus,
+ни раскрытия).
 
 ---
 
@@ -124,4 +166,77 @@ export const statusToClassNameMap = { [EMarkerStatus.SUCCESS]: styles.success, .
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-01 | Создан документ. AI-рефакторинг: `Marker` переведён с `React.FC` на `React.forwardRef` — `ref` теперь уходит на корневой `<span>` от `Badge.Dot`; добавлены JSDoc на компонент, `IMarkerProps.status`, значения `EMarkerStatus` и `STATUS_TO_CLASS_NAME_MAP`, карта закреплена через `satisfies Record<EMarkerStatus, string>`, поправлен порядок импортов. Карта переименована `statusToClassNameMap` → `STATUS_TO_CLASS_NAME_MAP` по `codestyle.md` (константа модульного уровня — UPPER_SNAKE_CASE); переименование внутреннее, `utils.ts` не входит ни в один barrel, синхронно обновлён импорт в `MarkerStatus.tsx`. Добавлены unit-тесты: `__tests__/Marker.test.tsx` (все статусы, проброс `size` в `Badge.Dot`, мердж `className`, `ref`, спред `...restProps`, `displayName`) и `__tests__/utils.test.tsx` (различимость и непустота классов карты статусов). Разметку точки и полную матрицу размеров не дублируем — их покрывает `Badge/__tests__/BadgeDot.test.tsx`; полноту карты статусов гарантирует `satisfies`. Заведены stories `stories/Marker/` в modern pattern. Публичный API (имена и типы props, значения `EMarkerStatus`, barrel-экспорты), разметка и визуальное поведение не изменены. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Marker/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Marker, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => <Marker status={EMarkerStatus.SUCCESS} size={EComponentSize.MD} />;
+```
+
+### Statuses
+
+`stories/Marker/examples/Statuses.tsx`
+
+```tsx
+import React from "react";
+import { Marker, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+const STATUSES = Object.values(EMarkerStatus);
+
+export const Statuses = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 32, flexWrap: "wrap" }}>
+        {STATUSES.map((status) => (
+            <div key={status}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
+                <Marker status={status} size={EComponentSize.MD} aria-hidden />
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Marker/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Marker, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 32, flexWrap: "wrap" }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Marker status={EMarkerStatus.SUCCESS} size={size} aria-hidden />
+            </div>
+        ))}
+    </div>
+);
+```
+
+### WithAccessibleName
+
+`stories/Marker/examples/WithAccessibleName.tsx`
+
+```tsx
+import React from "react";
+import { Marker, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const WithAccessibleName = () => (
+    <Marker status={EMarkerStatus.ERROR} size={EComponentSize.MD} role="img" aria-label="Ошибка" />
+);
+```
+