@sberbusiness/triplex-next-mcp-server 1.48.0-beta → 1.50.0-beta

package/bundle/components/SelectExtendedField.md

@@ -1,7 +1,7 @@
 ---
 component: SelectExtendedField
 category: SelectExtendedField
-related: [SelectField, MultiselectField, SuggestField, Chip, Dropdown, FormField, KeyDownListener, IconWrapper, LoaderSmall]
+related: [SelectField, MultiselectField, SuggestField, Dropdown, FormField, KeyDownListener, IconWrapper, LoaderSmall]
 tokens: []
 stories: stories/SelectExtendedField/SelectExtendedField.stories.tsx
 version: "1.0"
@@ -203,6 +203,7 @@ version: "1.0"
 |---|---|
 | 2026-08-07 | Создан документ AI-ready для `SelectExtendedField` (TRI-74). |
 | 2026-08-07 | AI-рефакторинг (TRI-74): `onOpen` / `onClose` сравнивают предыдущее значение `opened` вместо флага «смонтирован» — колбэки больше не срабатывают ложно при двойном маунте в React 18 StrictMode. Удалены ссылки на несуществующие CSS-классы в `SelectExtendedFieldTarget` (в `class` попадал литерал `undefined`). Клик по кнопке очистки больше не раскрывает выпадающий блок — всплытие останавливается, как в `Chip.Select`. Слушатель `mousedown` навешивается только пока блок открыт, callback-ref стабилизирован через `useCallback`, убран мёртвый внутренний `targetRef` в `SelectExtendedFieldTarget`, дедуплицирован список опций десктопной и мобильной версий в `SelectExtendedFieldDropdownDefault`. JSDoc на всех props, unit-тесты разбиты по субкомпонентам и расширены с 42 до 69 кейсов. Stories переведены на modern pattern. Публичный API не изменён. |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`Chip`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/SelectField.md

@@ -1,7 +1,7 @@
 ---
 component: SelectField
 category: SelectField
-related: [SelectExtendedField, MultiselectField, SuggestField, Chip, Dropdown, Pagination]
+related: [SelectExtendedField, MultiselectField, SuggestField, Dropdown, Pagination, FormField]
 tokens: []
 stories: stories/SelectField/SelectField.stories.tsx
 version: "1.0"
@@ -171,6 +171,8 @@ version: "1.0"
   `IChipSelectProps` собирается из `ISelectFieldProps`.
 - `Dropdown` — выпадающий блок, `DropdownList` / `DropdownListItem` и `DropdownListContext`,
   через который поднимается активная опция для `aria-activedescendant`.
+- `FormField` — семейство строительных блоков поля: `SelectExtendedField.Target` собран на `FormFieldTarget`,
+  поэтому лейбл, статусы и слоты приходят в публичный API `SelectField` оттуда.
 - `Pagination` — потребитель внутри библиотеки: `PaginationSelect` оборачивает `SelectField`
   для выбора количества элементов на странице и опирается на проброс `aria-labelledby`
   и на пустой `targetProps.fieldLabel`.
@@ -203,6 +205,7 @@ version: "1.0"
 | Дата | Изменение |
 |---|---|
 | 2026-09-03 | Создан документ (TRI-75). AI-рефакторинг: удалён мёртвый внутренний `targetRef`, внешний `ref` пробрасывается напрямую и больше не пересоздаётся на каждый рендер; идентификатор списка переведён с `useRef(uniqueId())` на `useState(() => uniqueId())`, чтобы счётчик не крутился на каждом рендере; параметры рендер-функций перестали затенять `props` компонента; импорты приведены к алиасу пакета; JSDoc на всех props и на компоненте. Unit-тесты расширены с 15 до 24 кейсов (`onChange` с аргументом, опции и выбранное значение, `aria-activedescendant` через `DropdownListContext`, стабильность `listId`, ref-target). Stories переведены на modern pattern, `States` разделена на `Statuses` и `Loading`. Публичный API не изменён |
+| 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны несимметричные имена (`Chip`); добавлены обратные ссылки (`FormField`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 
 ---
 

package/bundle/components/Skeleton.md

@@ -1,10 +1,14 @@
 ---
 component: Skeleton
-category: Feedback
-figma-node: ""
-figma-file: ""
-related: [Loader, LoaderScreen]
-tokens: [triplex-next-Skeleton-BackgroundColor_Light_Start, triplex-next-Skeleton-BackgroundColor_Light_End, triplex-next-Skeleton-BackgroundColor_Dark_Start, triplex-next-Skeleton-BackgroundColor_Dark_End]
+category: Loaders
+related: [LoaderMiddle]
+tokens:
+  - Skeleton.BackgroundColor_Type1_Start
+  - Skeleton.BackgroundColor_Type1_End
+  - Skeleton.BackgroundColor_Type2_Start
+  - Skeleton.BackgroundColor_Type2_End
+  - Skeleton.BackgroundColor_Type3_Start
+  - Skeleton.BackgroundColor_Type3_End
 stories: stories/Skeleton/Skeleton.stories.tsx
 version: "1.0"
 ---
@@ -13,112 +17,112 @@ version: "1.0"
 
 ## Назначение
 
-Плейсхолдер для загружающегося контента — пульсирующий `<div>` с
-`border-radius: 16px` и `flex-grow: 1`. Поддерживает две темы (`DARK` /
-`LIGHT`) — отличаются фоновыми переменными в @keyframes.
+Плейсхолдер-блок на месте контента, который ещё не загрузился: скруглённый прямоугольник, пульсирующий цветом фона. Форму и размер задаёт не компонент, а потребитель — собственных размеров у `Skeleton` нет.
 
-Используй когда: показываешь shape будущего контента, чтобы избежать
-layout shift и психологически сократить ощущаемое время загрузки. Для
-точечного индикатора — `Loader`/`LoaderScreen`.
+Используй когда: известна будущая раскладка экрана и нужно показать её каркас во время загрузки — карточки, строки списка, аватары, блоки текста. Скелетон сохраняет геометрию страницы и не даёт контенту «прыгать» после загрузки.
 
----
-
-## Файловая структура
-
-```text
-src/components/Skeleton/
-├── Skeleton.tsx               # FC; <div> + класс по type
-├── enums.ts                   # ESkeletonType (DARK | LIGHT)
-├── styles/Skeleton.module.less # 2 @keyframes пульсации
-├── index.ts
-└── __tests__/
-```
+Не используй когда:
+- Раскладка заранее неизвестна или загрузка короткая — возьми спиннер: `LoaderSmall` (внутри кнопки/поля), `LoaderMiddle` (внутри блока), `LoaderScreen` (поверх области с затемнением).
+- Нужно перекрыть уже отрисованный контент на время обновления — это `LoaderScreen`, а не скелетон.
+- Нужен просто пустой отступ — `Gap`.
 
 ---
 
 ## Варианты и props
 
-### `ISkeletonProps extends HTMLAttributes<HTMLDivElement>`
+### Обязательные props
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `type` | `ESkeletonType` | `DARK` | Тема (DARK/LIGHT). Влияет на анимационные переменные. |
-| `...HTMLAttributes` | — | — | На `<div>`. Размер задаётся через `style`/`className`. |
+Обязательных props нет.
 
-### Enum
+### Опциональные props
 
-- `ESkeletonType.DARK | LIGHT`.
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `type` | `ESkeletonType` | `ESkeletonType.TYPE_2` | Цветовая схема пульсации под фон, на котором лежит скелетон. |
 
----
+Компонент расширяет `React.HTMLAttributes<HTMLDivElement>` — принимает все стандартные атрибуты `<div>` (`className`, `style`, `aria-*`, `data-*` и т.д.).
 
-## Ключевые особенности реализации
+### Значения `ESkeletonType`
 
-### Анимация — 2s ease-in-out infinite через background-color keyframes
+| Значение | Заливка | Для какого фона |
+|---|---|---|
+| `TYPE_1` | Непрозрачные нейтральные серые | Светло-серые поверхности, где полупрозрачность «проваливается» и скелетон плохо виден |
+| `TYPE_2` (по умолчанию) | Полупрозрачный тёмный тинт | Обычные светлые поверхности (белая карточка, фон страницы) |
+| `TYPE_3` | Полупрозрачный светлый тинт | Тёмные и брендовые цветные поверхности |
 
-```less
-.skeleton.dark { animation: skeleton-dark-pulse 2s ease-in-out infinite; }
-@keyframes skeleton-dark-pulse {
-    0%   { background-color: var(--triplex-next-Skeleton-BackgroundColor_Dark_Start); }
-    50%  { background-color: var(--triplex-next-Skeleton-BackgroundColor_Dark_End); }
-    100% { background-color: var(--triplex-next-Skeleton-BackgroundColor_Dark_Start); }
-}
-```
+`TYPE_2` и `TYPE_3` — полупрозрачные: результат зависит от того, что лежит под скелетоном. В тёмной теме пары токенов инвертированы, поэтому смысл («тинт по контрасту к своей поверхности») сохраняется в обеих темах и подбирать `type` под тему вручную не нужно — только под фон.
 
-- Пульсация Start ↔ End ↔ Start.
-- **`prefers-reduced-motion`** не учитывается — потенциальный a11y-долг.
+### Ограничения
 
-### `border-radius: 16px`, `flex-grow: 1`
+- **У компонента нет собственных размеров.** В стилях заданы только `border-radius: 16px` и `flex-grow: 1`. Без размера от потребителя скелетон схлопнется в нулевую высоту. Задавай размер одним из способов: `style`/`className` с `width`/`height`, либо положи скелетон во flex-контейнер с заданной высотой — тогда сработает `flex-grow`.
+- `border-radius` фиксирован в стилях и через props не настраивается — перекрывается только собственным `className`/`style`.
+- `Skeleton` задуман как пустой плейсхолдер. `children` технически проходят на корневой `<div>` через spread и отрисуются, но контент внутри пульсирующего блока не предусмотрен дизайном — каркас из нескольких блоков собирается композицией нескольких `Skeleton` в разметке потребителя.
 
-- Скругление **захардкожено** (16px). Для других форм (круги аватаров, узкие линии текста) — потребитель override через className/style.
-- `flex-grow: 1` — растягивается во flex-контейнере. **В блочном родителе** Skeleton сам по себе не имеет ширины — нужна `style.width` или `className` с шириной.
+---
 
-### **`FC, не forwardRef`**
+## Дизайн-токены
 
-- Ref на `<div>` не пробрасывается.
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Skeleton.ts`.
 
-### **Нет `aria-busy`/`role="status"`**
+```text
+Skeleton.BackgroundColor_Type1_Start
+Skeleton.BackgroundColor_Type1_End
+Skeleton.BackgroundColor_Type2_Start
+Skeleton.BackgroundColor_Type2_End
+Skeleton.BackgroundColor_Type3_Start
+Skeleton.BackgroundColor_Type3_End
+```
 
-- Skeleton — чисто визуальный. AT не озвучивает «загрузка». Если важно — потребитель добавляет `role="status"` / `aria-busy="true"` через `...rest`.
+Пара `Start`/`End` задаёт ключевые кадры пульсации: `Start` — состояние на 0% и 100%, `End` — на 50%. Переопределять их имеет смысл только парой, иначе анимация станет несимметричной.
 
 ---
 
 ## Инварианты
 
-- **`type` default `DARK`**.
-- **`border-radius: 16px`** захардкожено — изменение требует override.
-- **`flex-grow: 1`** захардкожено — поведение во flex-контейнере.
-- **Анимация 2s ease-in-out infinite** — захардкожено, не настраивается.
-- **CSS-переменные `--triplex-next-Skeleton-BackgroundColor_{Light|Dark}_{Start|End}`** — публичные токены.
-- **`FC, не forwardRef`**.
-- **`prefers-reduced-motion` не учитывается** — тех-долг.
-- **`data-tx`** — версия пакета.
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<div>`.
+- **Имена публичного API**: компонент `Skeleton`, интерфейс `ISkeletonProps`, prop `type`, enum `ESkeletonType` и его строковые значения (`"type_1"`, `"type_2"`, `"type_3"`) — менять нельзя (breaking change).
+- **Дефолт `type` — `ESkeletonType.TYPE_2`.** Смена дефолта меняет внешний вид у всех, кто не передаёт `type` явно.
+- **`barrel src/components/Skeleton/index.ts`** экспортирует `./Skeleton` и `./enums` — оба экспорта сохранять.
+- **Корневой DOM-элемент — `<div>`** без ARIA-роли; собственного содержимого компонент не рендерит.
+- **`data-tx`** проставляется после спреда `...htmlDivAttributes`, то есть потребитель его не перекрывает. Порядок атрибутов в JSX не менять.
+- **CSS-классы `skeleton`, `type1`, `type2`, `type3`** в `Skeleton.module.less` проверяются unit-тестами. Visual baseline (`loaders-skeleton--visual-tests`) фиксирует только геометрию из `.skeleton`: в story анимация выключена декоратором, а фон задан inline, поэтому цвета типов визуальным тестом не покрыты — классы `type1/2/3` объявляют лишь `animation`, а цвет приходит из `@keyframes`.
+- **`displayName = "Skeleton"`** — проверяется тестом.
+- **Анимация задаётся только в LESS** (`skeleton-type{N}-pulse`, 2s ease-in-out infinite). Имена keyframes локальны для CSS-модуля; потребитель гасит анимацию своим `className`/`style` (story `Visual tests` для скриншотов делает это глобальным правилом `* { animation: none !important; }` в декораторе).
 
 ---
 
 ## Accessibility
 
-- **Нет `role` / `aria-busy`** по умолчанию — потребитель должен добавить, если нужно.
-- **Нет `prefers-reduced-motion` media-query** — анимация играет всегда. Пользователи с предпочтением reduced motion увидят пульсацию (тех-долг).
+Компонент не интерактивный и по смыслу декоративный: в штатном использовании это пустой `<div>` без роли, без текста, без фокуса. ARIA-семантику загрузки компонент намеренно не хардкодит — её задаёт потребитель на контейнере загружаемой области:
 
----
+- пометь область `aria-busy="true"` на время загрузки и сними атрибут после;
+- если пользователю нужно объявление о загрузке — сделай `aria-live`-регион с текстом рядом, скелетон для этого не подходит (библиотека мультиязычная, компонент не содержит текста);
+- сами скелетоны имеет смысл скрыть от скринридера (`aria-hidden="true"` через spread) — иначе в дереве доступности остаются пустые узлы.
 
-## Дизайн-токены
-
-- `--triplex-next-Skeleton-BackgroundColor_Light_Start` / `_End`.
-- `--triplex-next-Skeleton-BackgroundColor_Dark_Start` / `_End`.
+Ограничение: пульсация не отключается по `prefers-reduced-motion` — если это важно, гаси анимацию своим `className`.
 
 ---
 
 ## Связанные компоненты
 
-- `Loader` / `LoaderScreen` — для активной точечной загрузки.
+- `LoaderMiddle` (`src/components/Loader/`) — спиннер для блока или секции: альтернатива, решающая ту же задачу (первая загрузка блока) другим компромиссом — берётся, когда будущая раскладка заранее неизвестна.
+
+`LoaderSmall` (внутри кнопки или поля) и `LoaderScreen` (оверлей поверх уже отрисованного контента при обновлении) решают другие задачи, поэтому в `related` не входят — см. «Не используй когда».
 
 ---
 
 ## Stories
 
-`stories/Skeleton/Skeleton.stories.tsx`
-Примеры: `stories/Skeleton/examples/`
+Основные истории: `stories/Skeleton/Skeleton.stories.tsx`
+Файлы примеров: `stories/Skeleton/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный выбор `type` на макете из списка и карточек |
+| `Default` | `DefaultExample.tsx` | Четыре блока с размерами через `style`, тип по умолчанию |
+| `Types` | `TypesExample.tsx` | `TYPE_1`, `TYPE_2`, `TYPE_3`, каждый на подходящем ему фоне |
+| `VisualTests` | — | Скриншот-регрессия: все три типа с отключённой анимацией |
 
 ---
 
@@ -126,4 +130,71 @@ src/components/Skeleton/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-28 | Создан документ. AI-рефакторинг (TRI-76): `Skeleton` переведён с `React.FC` на `forwardRef`, добавлен `displayName`, JSDoc на интерфейсе props; unit-тесты расширены (ref, `displayName`, `data-tx`, проброс html-атрибутов). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Skeleton/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { Skeleton } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <div style={{ display: "flex", flexWrap: "wrap", gap: "24px", padding: "24px" }}>
+        <Skeleton style={{ height: "80px", width: "calc(50% - 12px)" }} />
+        <Skeleton style={{ height: "80px", width: "calc(50% - 12px)" }} />
+        <Skeleton style={{ height: "80px", width: "calc(50% - 12px)" }} />
+        <Skeleton style={{ height: "80px", width: "calc(50% - 12px)" }} />
+    </div>
+);
+```
+
+### Types
+
+`stories/Skeleton/examples/TypesExample.tsx`
+
+```tsx
+import React from "react";
+import { Skeleton, ESkeletonType } from "@sberbusiness/triplex-next";
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_1</div>
+            <div style={{ display: "flex", flexWrap: "wrap", gap: "24px", padding: "24px", background: "#EEF0F4" }}>
+                <Skeleton type={ESkeletonType.TYPE_1} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_1} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_1} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_1} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+            </div>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_2</div>
+            <div style={{ display: "flex", flexWrap: "wrap", gap: "24px", padding: "24px" }}>
+                <Skeleton type={ESkeletonType.TYPE_2} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_2} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_2} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_2} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+            </div>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_3</div>
+            <div
+                className="skeleton-type3-background"
+                style={{ display: "flex", flexWrap: "wrap", gap: "24px", padding: "24px" }}
+            >
+                <Skeleton type={ESkeletonType.TYPE_3} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_3} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_3} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+                <Skeleton type={ESkeletonType.TYPE_3} style={{ height: "80px", width: "calc(50% - 12px)" }} />
+            </div>
+        </div>
+    </div>
+);
+```
+