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

package/bundle/components/EmptyView.md

@@ -0,0 +1,99 @@
+---
+component: EmptyView
+category: Feedback
+figma-node: "80-48"
+figma-file: "https://www.figma.com/design/lpkxmWZ512mG2OJyDvGtHD/-W--LIB-DSN-01-Components-DCB-Next-v.1.3.0"
+related: [Button]
+tokens:
+  - --triplex-next-Typography-Primary_Color
+  - --triplex-next-Typography-Secondary_Color
+stories: stories/EmptyView/EmptyView.stories.tsx
+version: "1.0"
+---
+
+# EmptyView
+
+## Назначение
+
+Компонент для отображения пустых состояний: нет данных, сервис недоступен, нет результатов поиска и т.д.
+
+Используй когда: нужно показать заглушку при отсутствии контента.
+Не используй когда: есть контент для отображения или нужно показать ошибку загрузки (используй Alert).
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `EEmptyViewSize` | Размер: SM / MD |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `icon` | `ReactNode` | — | Иконка (96px для SM, 128px для MD) |
+| `title` | `ReactNode` | — | Заголовок |
+| `description` | `ReactNode` | — | Текст описания |
+| `caption` | `ReactNode` | — | Подпись |
+| `buttons` | `ReactNode` | — | Кнопки действий |
+
+### Поведение описания
+
+- Если `title` задан: описание отображается вторичным цветом (Secondary)
+- Если `title` не задан: описание становится основным текстом (Primary)
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-Typography-Primary_Color    (title, description без title)
+--triplex-next-Typography-Secondary_Color  (description с title, caption)
+```
+
+---
+
+## Инварианты
+
+- `forwardRef` на компоненте — не убирать
+- `EEmptyViewSize` — публичный enum, менять значения нельзя
+- CSS-классы `emptyView`, `hasTitle` используются в тестах
+
+---
+
+## Accessibility
+
+- Компонент не требует обязательных aria-атрибутов
+- Потребитель может передать `role`, `aria-label` и другие атрибуты через spread
+
+---
+
+## Связанные компоненты
+
+- `Button` — используется в `buttons` для действий
+
+---
+
+## Stories
+
+Основные истории: `stories/EmptyView/EmptyView.stories.tsx`
+Файлы примеров: `stories/EmptyView/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
+| `Default` | `DefaultExample.tsx` | Минимальное состояние с title, description и caption |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD |
+| `WithoutTitle` | `WithoutTitleExample.tsx` | Вариант без заголовка |
+| `WithButtons` | `WithButtonsExample.tsx` | Вариант с кнопками действий |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-09 | Создан компонент и документ |

package/bundle/components/ExpandAnimation.md

@@ -0,0 +1,281 @@
+---
+component: ExpandAnimation
+category: Animation
+figma-node: ""
+figma-file: ""
+related: [AccordionBase, Spoiler, IslandAccordion, CollapsableTree]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# ExpandAnimation
+
+## Назначение
+
+Инфраструктурный компонент-"анимация": плавное сворачивание/разворачивание
+блока по высоте (`height: 0 ↔ scrollHeight`) через `react-transition-group`.
+Используется в `AccordionBase`, `IslandAccordion`, `Spoiler`,
+`CollapsableTree` и любом compound'е, где нужно "раскрыть / свернуть"
+блок.
+
+Ключевая задача — **анимация CSS через height** (у которой нет `auto` в
+transitions), реализованная через явное измерение `scrollHeight` и
+переключение между `0 ↔ измеренная высота` в нужные моменты жизненного
+цикла Transition.
+
+Используй когда: строишь собственный компонент с разворачивающимся
+блоком. Подписывайся на `onStart`/`onEnd` для syncронизации логики.
+Не используй как: универсальная анимация "fade" — только expand/collapse.
+
+---
+
+## Файловая структура
+
+```text
+src/components/ExpandAnimation/
+├── ExpandAnimation.tsx                       # forwardRef, Transition wrapper
+├── index.ts                                  # Barrel
+└── styles/
+    ├── ExpandAnimation.module.less           # .expandAnimation { transition-property: height; timing: ease-in-out }
+    └── ExpandedAnimation.module.less         # дубликат-остаток (см. ниже)
+```
+
+Особенности:
+- **`forwardRef`** — есть.
+- **`ExpandedAnimation.module.less`** — дублирующийся файл с тем же
+  содержимым (`.expandedAnimation` вместо `.expandAnimation`). Не
+  импортируется компонентом, legacy-остаток. **Не удалять
+  отдельным коммитом без проверки потребителей** — возможно, кто-то
+  импортирует его напрямую.
+- **Нет `__tests__`** — покрывается через потребителей
+  (AccordionBase-tests проверяют анимацию косвенно).
+- **Нет stories** — внутренний/инфраструктурный.
+- **Без `data-tx`** — не ставит атрибут версии.
+
+---
+
+## Варианты и props
+
+### `IExpandAnimationProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `expanded` | `boolean` | — (обязателен) | Целевое состояние: раскрыт/свёрнут. Controlled. |
+| `animationTime` | `number` | `300` (мс) | Длительность transition. Идёт в `timeout` Transition'а и в `transitionDuration` inline-стиля. |
+| `onStart` | `() => void` | — | Срабатывает в начале анимации (onEnter и onExit). |
+| `onEnd` | `() => void` | — | Срабатывает в конце анимации (onEntered и onExited). |
+| `transitionProps` | `React.ComponentProps<typeof Transition<HTMLDivElement>>` | — | Дополнительные пропсы для `Transition`. Колбэки мержатся (см. ниже). |
+| `className`, `style`, `children`, `...HTMLDivAttributes` | — | — | Стандартные. |
+
+---
+
+## Ключевые особенности реализации
+
+### Transition статусы → inline-styles
+
+```ts
+const transitionStylesRef = useRef<Record<TransitionStatus, React.CSSProperties>>({
+    entering: { height: undefined, overflow: "hidden" },  // height задаётся в onEnter
+    entered: {},
+    exiting: { height: 0, overflow: "hidden" },
+    exited: { height: 0, overflow: "hidden", visibility: "hidden" },
+    unmounted: {},
+});
+```
+
+**Состояния:**
+- **`entering`** — начало раскрытия. `height` проставляется **в
+  момент onEnter**, до этого `undefined` (браузер рендерит от 0 к
+  `scrollHeight`).
+- **`entered`** — раскрыт. Пусто — браузер держит естественную высоту
+  (`auto`).
+- **`exiting`** — начало сворачивания. `height: 0` + `overflow: hidden`.
+- **`exited`** — свёрнут. `height: 0 + overflow: hidden + visibility: hidden`.
+  `visibility: hidden` убирает из tab-order.
+- **`unmounted`** — компонент размонтирован, пусто.
+
+**useRef** — объект не пересоздаётся между рендерами, ссылки на
+`CSSProperties` стабильны.
+
+### Измерение высоты в onEnter
+
+```ts
+const handleEnter = (appearing) => {
+    if (nodeRef.current) {
+        transitionStylesRef.current["entering"].height = nodeRef.current.scrollHeight;
+    }
+    onStart?.();
+    transitionProps?.onEnter?.(appearing);
+};
+```
+
+**`scrollHeight` читается из DOM** — это реальная высота содержимого.
+Браузер проанимирует от `0` до этого значения. Почему в onEnter:
+перед ним height был `0`, после onEnter — DOM получит конкретное
+значение для transition to.
+
+**Проблема "height: auto в transitions":** CSS не может transition
+между `0` и `auto`. ExpandAnimation решает это, подставляя реальное
+число.
+
+### onExit: hack с `scrollHeight` и force reflow
+
+```ts
+const handleExit = () => {
+    if (nodeRef.current) {
+        nodeRef.current.style.height = nodeRef.current.scrollHeight + "px";
+        // trigger reflow
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+        nodeRef.current.scrollHeight;
+    }
+    onStart?.();
+    transitionProps?.onExit?.();
+};
+```
+
+**Последовательность:**
+1. Ставим `style.height = scrollHeight + "px"` — конкретное значение,
+   от которого пойдёт transition.
+2. **Force reflow** — читаем `scrollHeight` "впустую" (expression с
+   lint-ignore). Без этого браузер может "оптимизировать" и не
+   зафиксировать промежуточный state — transition пойдёт от "auto"
+   сразу к "0" без плавности.
+3. Вызываем `onStart` и обёрнутый колбэк.
+4. React-Transition-Group затем переключит в `exiting`, где inline
+   style из `transitionStylesRef` ставит `height: 0` → браузер
+   анимирует от запомненной высоты до 0.
+
+**Не удалять `nodeRef.current.scrollHeight;` "пустое" чтение** — это
+**is** reflow trigger. Без него анимация не работает.
+
+### `nodeRef` — обязательный для Transition с `nodeRef` паттерном
+
+```tsx
+<Transition in={expanded} timeout={animationTime} nodeRef={nodeRef} ...>
+```
+
+`react-transition-group` v4+ требует `nodeRef` для strict-mode
+совместимости (вместо `findDOMNode`). `nodeRef` в ExpandAnimation
+ставится через `setRef` (который также форвардит внешний ref).
+
+### Слияние колбэков Transition
+
+```tsx
+<Transition
+    {...transitionProps}
+    onEnter={handleEnter}      // переопределяет transitionProps.onEnter
+    onEntered={handleEntered}
+    onExit={handleExit}
+    onExited={handleExited}
+>
+```
+
+**`handle*` вызывают `transitionProps?.onEnter?.(...)` и т. п.** — так
+что если пользователь передал свои `onEnter` через transitionProps,
+они всё равно выполнятся, но **после** наших handler'ов.
+
+**Порядок:** наш handler → (onStart для start-ветки) → user's onEnter/Exit.
+
+### `style` inline — слияние трёх источников
+
+```tsx
+style={{
+    transitionDuration: animationTime + "ms",
+    ...transitionStylesRef.current[state],
+    ...style,
+}}
+```
+
+**Порядок:** дефолт duration → наш state-style → пользовательский
+`style`. Пользовательский стиль побеждает — он может подрезать
+наше поведение, если потребитель этого хочет.
+
+### `setRef` — double-duty ref
+
+```ts
+const setRef = (instance) => {
+    nodeRef.current = instance;
+    if (typeof ref === "function") ref(instance);
+    else if (ref) ref.current = instance;
+};
+```
+
+Внутренний `nodeRef` (для Transition) + внешний forwarded ref.
+
+### Дубликат файла `ExpandedAnimation.module.less`
+
+Файл существует, но **не используется** компонентом. Вероятно legacy
+от переименования. Не удалять без проверки прямого импорта из
+потребителей (`grep -r "ExpandedAnimation"`).
+
+---
+
+## Инварианты
+
+- **`nodeRef.current.scrollHeight;` в handleExit** — force reflow.
+  Не удалять. Без него transition ломается.
+- **`expanded` — controlled only** — нет defaultExpanded.
+- **Состояние inline-styles в `transitionStylesRef`** — мутабельные
+  объекты, храним в ref чтобы не пересоздавать.
+- **Transition `nodeRef`** — обязателен (v4+ API).
+- **`visibility: hidden` в exited** — убирает из tab-order. Не
+  менять на `display: none` (сломает transition).
+- **`transitionProps` колбэки вызываются после наших** — порядок
+  важен, не менять.
+- **`animationTime` синхронизирован между `timeout` Transition'а и
+  `transitionDuration`** — не менять одно без другого.
+- **`data-tx`** — не проставляется (нестандартно для библиотеки,
+  возможен debt).
+- **`forwardRef`** — есть.
+
+---
+
+## Accessibility
+
+- **`visibility: hidden` в свёрнутом состоянии** — убирает элементы
+  из tab-order и screen reader'а. Важный инвариант для "раскрытые
+  элементы не доступны клавиатурой".
+- **`overflow: hidden`** в анимации — скрывает частично видимый
+  контент.
+- **`aria-expanded`** — **не** проставляется ExpandAnimation. Это
+  задача потребителя (AccordionBase делает это).
+- **`onStart`/`onEnd`** — позволяют потребителю обновить ARIA-state
+  в правильный момент (например, объявить "свернуто" для screen
+  reader'а после завершения).
+
+---
+
+## Дизайн-токены
+
+**Нет.** Чистая инфраструктура анимации.
+
+---
+
+## Связанные компоненты
+
+- `AccordionBase` (`src/components/AccordionBase/protected/AccordionBase`) —
+  главный потребитель. Оборачивает ExpandAnimation + добавляет
+  `aria-expanded`, заголовок, клик.
+- `IslandAccordion` (`src/components/IslandAccordion`) — использует
+  ExpandAnimation напрямую или через AccordionBase.
+- `Spoiler` (`src/components/Spoiler`) — альтернатива без заголовка-
+  кнопки.
+- `CollapsableTree` (`src/components/CollapsableTree`) — composes
+  ExpandAnimation через AccordionBase.
+- `react-transition-group` — внешняя зависимость.
+
+---
+
+## Stories
+
+**Нет собственных stories.** Инфраструктурный компонент. Видно в
+действии через AccordionBase/Spoiler/IslandAccordion stories.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |