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

package/bundle/components/MarkerStatus.md

@@ -1,9 +1,7 @@
 ---
 component: MarkerStatus
-category: Feedback
-figma-node: ""
-figma-file: ""
-related: [Marker, Badge, Typography]
+category: MarkerStatus
+related: [TagColor, Marker, Text, Caption]
 tokens: []
 stories: stories/MarkerStatus/MarkerStatus.stories.tsx
 version: "1.0"
@@ -13,131 +11,178 @@ version: "1.0"
 
 ## Назначение
 
-Статус-блок: цветная точка (`Marker`) + заголовок (`children`) + опциональное
-описание. Окрашивает **текст заголовка/описания** цветом статуса через
-общий `statusToClassNameMap` (из `Marker/utils`). Два размера — MD / LG.
+Неинтерактивная подпись состояния: цветная точка-маркер слева, наименование статуса
+справа и необязательное описание под наименованием. Собственного состояния, логики и
+обработчиков нет — компонент собирает разметку из трёх частей и раздаёт классы по
+`size` и `status`.
 
-Используй когда: нужна компактная семантическая индикация состояния с
-подписью (успех операции, ошибка, 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
-```
+Не используй когда:
+- Нужен интерактивный элемент (клик, фокус, клавиатура) — возьми `Chip` или `Button`.
+- Нужна только точка без подписи — `Marker` (или `Badge.Dot`, если статусная палитра
+  не нужна).
+- Нужен статус на цветной подложке — `TagColor` или `Badge`.
+- Нужен многошаговый прогресс процесса — `StatusTracker`, он строит цепочку шагов и
+  использует `MarkerStatus` внутри (`StatusTracker.Body.Status`).
 
 ---
 
 ## Варианты и 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`. |
-
----
+`IMarkerStatusProps extends React.HTMLAttributes<HTMLDivElement>`: любой стандартный
+атрибут `<div>` (`id`, `role`, `aria-*`, `data-*`, `style`, обработчики) уходит на
+корневой элемент через `...rest`. `className` объединяется с базовыми классами через
+`clsx`, а не заменяет их.
 
-## Ключевые особенности реализации
-
-### Размер = `EComponentSize.MD | EComponentSize.LG`
-
-```ts
-size?: EComponentSize.MD | EComponentSize.LG;
-```
+### Обязательные props
 
-- **SM запрещён на уровне типа**. Если передать `SM` — TS ошибка. Для runtime-значения — визуал не определён.
-- Если появится требование SM — добавить маппинги `sizeToClassNameMap`, `markerStatusSizeToTextSizeMap` и LESS-стиль.
+| Prop | Тип | Описание |
+|---|---|---|
+| `status` | `EMarkerStatus` | `SUCCESS` / `ERROR` / `WARNING` / `WAITING`. Задаёт цвет точки-маркера. Enum объявлен в `src/components/Marker/enums.ts` и экспортируется из barrel `Marker` |
 
-### `size` пробрасывается в `Marker` (Badge.Dot)
+### Опциональные props
 
-```tsx
-<Marker status={status} size={size} />
-```
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize.MD \| EComponentSize.LG` | `EComponentSize.MD` | Размер маркера, типографики и отступов. `EComponentSize.SM` не поддерживается — union сужен намеренно, класса `sm` в стилях нет |
+| `children` | `React.ReactNode` | — | Наименование статуса. Всегда оборачивается в `Text` (`B4` для MD, `B3` для LG) — обёртка рендерится даже при пустом значении |
+| `description` | `React.ReactNode` | — | Описание под наименованием. Для MD — `Caption` `C1`, для LG — `Text` `B4`; в обоих случаях `type={EFontType.SECONDARY}` |
 
-- Marker получает `size` через `...IBadgeDotProps` — `Badge.Dot` сам определяет, как размер влияет на диаметр точки.
+### Размеры
 
-### Маппинг размера → typography-размер
+| | MD | LG |
+|---|---|---|
+| Наименование | `Text` `B4` | `Text` `B3` |
+| Описание | `Caption` `C1` | `Text` `B4` |
+| Диаметр точки | 8px (`Badge.Dot` MD) | 10px (`Badge.Dot` LG) |
+| Отступ маркер → текст | 4px | 6px |
+| Отступ наименование → описание | 0 | 4px |
+| Верхний отступ маркера | 4px | 5px |
 
-```ts
-const markerStatusSizeToTextSizeMap = {
-    [EComponentSize.MD]: ETextSize.B4,
-    [EComponentSize.LG]: ETextSize.B3,
-};
-```
+Верхний отступ маркера — оптическое выравнивание точки по первой строке
+наименования, значения подобраны под конкретные высоты строк типографики. При смене
+размеров текста их нужно пересчитывать.
 
-- MD → B4, LG → B3. Публичный контракт (визуальная спецификация).
+### Falsy-значения `description`
 
-### `description` — разный компонент по размеру
+Описание рендерится по truthy-проверке (`description && ...`). Поэтому
+`description=""` и `description={false}` не выводят ни текста, ни обёртки, а
+`description={0}` выводит голый `0` мимо `Caption` / `Text` — без вторичного цвета и
+размера. Для числовых значений передавай строку. Это исторически сложившееся
+поведение; менять его — задача с записью в release notes.
 
-```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
+Собственных токенов в стилях компонента нет: `styles/MarkerStatus.module.less`
+задаёт только раскладку (flex, отступы, выравнивание). Цвета приходят из вложенных
+компонентов и переопределяются через их группы токенов — см. `ThemeProvider-ai.md` →
+«Как переопределять токены».
 
-```tsx
-<div className={clsx(styles.markerStatus, sizeToClassNameMap[size], statusToClassNameMap[status], className)}>
+```text
+Marker.Background_Success
+Marker.Background_Error
+Marker.Background_Warning
+Marker.Background_Waiting
+Typography.Secondary_Color
 ```
 
-- **Переиспользование** CSS-Modules класса из `Marker/styles` — заложена **кросс-файловая зависимость**: `Marker/utils.ts` импортирует `Marker.module.less`. Если стили MarkerStatus переопределяют цвет текста, то они опираются на то, что корневой класс `.success/.error/...` уже задан.
+- Цвет точки — токены группы `Marker` (`src/components/DesignTokens/components/Marker.ts`),
+  применяются внутри `Marker`.
+- Цвет наименования — `Typography.Primary_Color` (дефолтный `EFontType.PRIMARY`),
+  цвет описания — `Typography.Secondary_Color` (`EFontType.SECONDARY`).
+
+**Известное расхождение:** группа `MarkerStatus` в
+`src/components/DesignTokens/components/MarkerStatus.ts` объявляет токен
+`MarkerStatus.Description_Color`, но ни один LESS-файл его не читает — описание
+красится через типографику. Токен остался от прежней реализации, его переопределение
+через `ThemeProvider` ни на что не влияет. Удаление токена и его css-переменной —
+изменение публичного API, делается отдельной задачей с записью в release notes
+(прецедент — `ImageGallery.Arrow_*_Disabled` в 1.45.0). Поэтому во frontmatter
+`tokens:` он не перечислен: список описывает токены, которые компонент реально
+использует.
 
 ---
 
 ## Инварианты
 
-- **`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}`** — маркер версии. Сохранять.
+- **`forwardRef`** — ref пробрасывается на корневой `<div>`; не убирать.
+- **Корневой элемент — `<div>`** с классами `markerStatus` + размер + статус. Внутри
+  ровно две обёртки: `markerContainer` (точка) и `contentContainer` (наименование и
+  описание). На эту структуру опираются unit-тесты; `StatusTrackerStatus` дописывает
+  корневому элементу свой класс `statusTrackerStatus`.
+- **Классы статуса на корне приходят из CSS-модуля `Marker`** —
+  `STATUS_TO_CLASS_NAME_MAP` импортируется из `src/components/Marker/utils.ts`, где
+  правила объявлены как `.marker.success` и т.п. На корне `MarkerStatus` эти классы
+  визуального эффекта не дают, но присутствуют в разметке и проверяются unit-тестами
+  (`toHaveClass("success")`). Не удалять без согласования: класс виден потребителю в
+  DOM.
+- **`size` сужен до `MD | LG`.** Расширение до полного `EComponentSize` требует
+  класса `sm` в стилях, размеров типографики и верхнего отступа маркера — это новая
+  функциональность, а не рефакторинг.
+- **`data-tx` ставится после `...restProps`** — потребитель не может переопределить
+  метку версии пакета. Порядок атрибутов в JSX менять нельзя, на это есть тест.
+- **`displayName`** — `MarkerStatus`; виден в React DevTools.
+- **`IMarkerStatusProps` — часть публичного API `StatusTracker`:**
+  `StatusTrackerStatus` типизирован как `React.FC<IMarkerStatusProps>`
+  (`src/components/StatusTracker/components/StatusTrackerStatus.tsx`). Любое изменение
+  формы интерфейса автоматически меняет публичный API `StatusTracker.Body.Status`.
 
 ---
 
 ## Accessibility
 
-- `<div>` — без ARIA-роли. Статус должен читаться скринридером через **текст в children**. Не полагайся только на цвет.
-- Если children тоже визуально отражает статус (например, "Ошибка"), и нужна дополнительная семантика — добавь `role="status"` через `...rest` или оборачивай MarkerStatus в live region.
-- Цвет текста — только как визуальный акцент. WCAG-контраст контролируется токенами `SECONDARY`/статус-цветами; при кастомных темах — проверить.
-
----
-
-## Дизайн-токены
-
-Нет публичных переменных компонента; цвета текста статусов заданы в
-`styles/MarkerStatus.module.less`. Цвет точки — через `Marker`.
+- Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру, ролей и
+  aria-атрибутов не выставляет. Смысл статуса несёт текст в `children`, поэтому для
+  скринридера подпись читается как обычный текст.
+- **Точка-маркер не имеет доступного имени** — это чисто визуальное дублирование
+  статуса, продублированное текстом рядом. Отдельная подпись ей не нужна.
+- Если статус меняется динамически (например, документ переходит из «Ожидает» в
+  «Исполнен») и об этом нужно сообщить скринридеру — потребитель сам передаёт
+  `role="status"` или `aria-live` через `...rest`. Компонент их не выставляет.
+- Строки на конкретном языке компонент не хардкодит — весь текст приходит от
+  потребителя.
 
 ---
 
 ## Связанные компоненты
 
-- `Marker` — цветная точка; то же `EMarkerStatus` и `statusToClassNameMap`.
-- `Badge.Dot` — база для Marker.
-- `Typography` (`Text`, `Caption`) — для заголовка и описания.
-- `TagColor` — альтернатива с фоном-пилюлей.
+- `Marker` (`src/components/Marker/Marker.tsx`) — точка со статусной палитрой,
+  рендерится внутри `MarkerStatus`; из его CSS-модуля берётся и `STATUS_TO_CLASS_NAME_MAP`
+  для корневого элемента.
+- `Text`, `Caption` — типографика наименования и описания; размеры и `EFontType`
+  выбираются по `size`.
+- `Badge` — не альтернатива и не прямая зависимость `MarkerStatus`: он решает другой
+  класс задач (статус на цветной подложке, счётчик), а в цепочку рендера попадает
+  через `Marker`, который построен на `Badge.Dot`. Поэтому во `related` не вынесен.
+- `TagColor` — альтернатива, когда статус показывается цветным тегом.
+- `StatusTracker` — потребитель: `StatusTracker.Body.Status` (`StatusTrackerStatus`)
+  оборачивает `MarkerStatus`, добавляя свой класс, и переиспользует `IMarkerStatusProps`.
+  Обёртка объявлена как `React.FC`, то есть ref до `MarkerStatus` через неё не доходит.
 
 ---
 
 ## Stories
 
-`stories/MarkerStatus/MarkerStatus.stories.tsx`
-Примеры: `stories/MarkerStatus/examples/`
+Основные истории: `stories/MarkerStatus/MarkerStatus.stories.tsx`
+Файлы примеров: `stories/MarkerStatus/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный подбор `status`, `size`, `description` и текста |
+| `Default` | `DefaultExample.tsx` | Минимальный вызов: `SUCCESS`, размер MD, описание |
+| `Statuses` | `StatusesExample.tsx` | Все четыре статуса в размере MD |
+| `Sizes` | `SizesExample.tsx` | Статусы в размерах MD и LG |
+
+Скриншот-регрессия снимается со стори `Statuses` и `Sizes`
+(`__screenshots__/markerstatus--statuses--xs|xl.png`,
+`__screenshots__/markerstatus--sizes--xs|xl.png`). `Playground` и `Default` исключены
+через `testRunner: { skip: true }`: первый — интерактивная песочница, второй полностью
+покрыт стори `Sizes`.
 
 ---
 
@@ -145,4 +190,77 @@ size === EComponentSize.MD
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-01 | Создан документ. AI-рефакторинг: добавлен `displayName`, `data-tx` перенесён после `...restProps` (потребитель больше не может его переопределить), в `IMarkerStatusProps` добавлен явный `children` (тип совпадает с унаследованным из `React.HTMLAttributes`), JSDoc на props и компонент, модульные константы приведены к UPPER_SNAKE_CASE, порядок импортов — по `codestyle.md`. Unit-тесты расширены с 4 до 15 кейсов: типографика наименования и описания по размерам, отсутствие описания, `description` как узел, проброс `status` / `size` в `Marker`, мердж `className`, `...rest`, `data-tx`, `ref`, `displayName`. Публичный API, DOM-структура и визуальное поведение не изменены. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/MarkerStatus/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { MarkerStatus, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <MarkerStatus status={EMarkerStatus.SUCCESS} size={EComponentSize.MD} description="Description">
+        Status text
+    </MarkerStatus>
+);
+```
+
+### Statuses
+
+`stories/MarkerStatus/examples/StatusesExample.tsx`
+
+```tsx
+import React from "react";
+import { MarkerStatus, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+const STATUSES = Object.values(EMarkerStatus);
+
+export const StatusesExample = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: "32px", flexWrap: "wrap" }}>
+        {STATUSES.map((status) => (
+            <div key={status}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{status.toUpperCase()}</div>
+                <MarkerStatus status={status} size={EComponentSize.MD} description="Description">
+                    Status text
+                </MarkerStatus>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/MarkerStatus/examples/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import { MarkerStatus, EMarkerStatus, EComponentSize } from "@sberbusiness/triplex-next";
+
+const STATUSES = Object.values(EMarkerStatus);
+const SIZES = [EComponentSize.MD, EComponentSize.LG] as const;
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "32px" }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+                <div style={{ display: "flex", alignItems: "flex-start", gap: "32px", flexWrap: "wrap" }}>
+                    {STATUSES.map((status) => (
+                        <MarkerStatus key={status} status={status} size={size} description="Description">
+                            Status text
+                        </MarkerStatus>
+                    ))}
+                </div>
+            </div>
+        ))}
+    </div>
+);
+```
+

package/bundle/components/MaskedField.md

@@ -57,7 +57,7 @@ version: "1.0"
 
 ## Дизайн-токены
 
-Собственных CSS-токенов и стилей у `MaskedField` нет — поэтому `tokens` во frontmatter пустой. Внешний вид наследуется от семейства `FormField`; слой подсказки маски рисует `FormFieldMaskedInput` своим токеном `--triplex-next-FormField-Placeholder_Color`.
+Собственных CSS-токенов и стилей у `MaskedField` нет — поэтому `tokens` во frontmatter пустой. Внешний вид наследуется от семейства `FormField`; слой подсказки маски рисует `FormFieldMaskedInput` своим токеном `FormField.Placeholder_Color`.
 
 ---
 
@@ -65,7 +65,6 @@ version: "1.0"
 
 - `forwardRef` на `MaskedField` — не убирать. Внешний `ref` указывает на корневой `<div>` `FormField`.
 - Публичный API (`IMaskedFieldProps`: `maskedInputProps` + `label`/`prefix`/`postfix`/`description`/`counter` + унаследованные `size`/`status`/`active`) — изменение имён/типов/значений enum — breaking change.
-- Barrel `index.ts` экспортирует `TextField` и `MaskedField` — состав экспортов не менять. `TextFieldBase` намеренно НЕ экспортируется — приватная база.
 - Ссылка на элемент input передаётся только через `maskedInputProps.forwardedRef`. `maskedInputProps.ref` (`React.RefObject<HTMLDivElement>`) попадает на корневой `<div>` обёртки `FormFieldMaskedInput` — это ref самого `FormFieldMaskedInput`, а не поля ввода.
 - `maskedInputProps.value` обязателен: `FormFieldMaskedInput` — контролируемый компонент. `defaultValue` исключён из props (`Omit<MaskedInputProps, ... | "defaultValue">`) и не передаётся внутрь `<input>`: `react-text-mask` подставляет его равным `value`, а на контролируемом поле это даёт предупреждение React о смешении controlled и uncontrolled.
 - Маски и подсказки берутся из `FormFieldMaskedInput.presets` — состав пресетов и их значения часть публичного API.
@@ -85,8 +84,7 @@ version: "1.0"
 
 ## Связанные компоненты
 
-- `TextField` — сосед по папке: то же поле, но с обычным `FormFieldInput`. Документируется отдельно.
-- `TextFieldBase` (внутренний, не в barrel) — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`. На нём построены `TextField` и `MaskedField`. Описан в `TextField-ai.md`.
+- `TextFieldBase` — базовая раскладка `FormGroup`/`FormField` + слоты `prefix`/`children`/`label`/`postfix` и блок `description`/`counter`.
 - `FormFieldMaskedInput` — сам элемент ввода с маской и статическим свойством `presets` (`masks`, `placeholderMasks`). Используется напрямую, когда нужна нестандартная композиция поля.
 - `FormFieldClear` — кнопка очистки, передаётся в `postfix`.
 - `FormGroup` / `FormField` — контейнеры раскладки поля и описания.