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

package/bundle/components/ExpandAnimation.md

@@ -1,11 +1,9 @@
 ---
 component: ExpandAnimation
-category: Animation
-figma-node: ""
-figma-file: ""
-related: [AccordionBase, Spoiler, IslandAccordion, CollapsableTree]
+category: ExpandAnimation
+related: [AccordionBase]
 tokens: []
-stories: ""
+stories: stories/ExpandAnimation/ExpandAnimation.stories.tsx
 version: "1.0"
 ---
 
@@ -13,269 +11,316 @@ version: "1.0"
 
 ## Назначение
 
-Инфраструктурный компонент-"анимация": плавное сворачивание/разворачивание
-блока по высоте (`height: 0 ↔ scrollHeight`) через `react-transition-group`.
-Используется в `AccordionBase`, `IslandAccordion`, `Spoiler`,
-`CollapsableTree` и любом compound'е, где нужно "раскрыть / свернуть"
-блок.
+Обёртка, анимирующая раскрытие и сворачивание содержимого по высоте. Своего
+состояния не хранит: раскрытость целиком задаётся пропом `expanded` со стороны
+потребителя. Внутри — `Transition` из `react-transition-group`, поверх которого
+надстроены измерение высоты контента и инлайн-стили фаз анимации.
 
-Ключевая задача — **анимация CSS через height** (у которой нет `auto` в
-transitions), реализованная через явное измерение `scrollHeight` и
-переключение между `0 ↔ измеренная высота` в нужные моменты жизненного
-цикла Transition.
+Собственного оформления у компонента нет — только `transition-property: height`
+и `transition-timing-function: ease-in-out`. Это строительный блок, а не
+готовый UI.
 
-Используй когда: строишь собственный компонент с разворачивающимся
-блоком. Подписывайся на `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`** — не ставит атрибут версии.
+Не используй когда: нужен готовый аккордеон с внутренним состоянием, id-связкой
+заголовка и тела и ARIA-атрибутами — для этого есть `AccordionBase` и
+построенные на нём компоненты.
 
 ---
 
 ## Варианты и props
 
-### `IExpandAnimationProps extends React.HTMLAttributes<HTMLDivElement>`
+`IExpandAnimationProps` расширяет `React.HTMLAttributes<HTMLDivElement>` —
+`...rest` уходит на корневой `<div>`.
 
-| 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` | — | — | Стандартные. |
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `expanded` | `boolean` | Развёрнут ли блок. Управляемое свойство, внутреннего состояния нет |
 
-## Ключевые особенности реализации
+### Опциональные props
 
-### Transition статусы → inline-styles
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `animationTime` | `number` | `300` | Длительность анимации в мс. Одновременно уходит в `timeout` у `Transition` и в инлайн-стиль `transition-duration` — задавать их врозь нельзя |
+| `onStart` | `() => void` | — | Начало анимации. Вызывается **и при разворачивании, и при сворачивании** (из `onEnter` и `onExit`) |
+| `onEnd` | `() => void` | — | Конец анимации. Вызывается **и при разворачивании, и при сворачивании** (из `onEntered` и `onExited`) |
+| `transitionProps` | `React.ComponentProps<typeof Transition<HTMLDivElement>>` | — | Сквозные props для внутреннего `Transition` |
+| `className` | `string` | — | Мерджится с собственным классом через `clsx` |
+| `style` | `React.CSSProperties` | — | Разливается **после** стилей фазы анимации, поэтому переопределяет `height` / `overflow` / `visibility`. Передавать `height` здесь — значит сломать анимацию |
 
-```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?.();
-};
-```
+| Фаза `TransitionStatus` | Инлайн-стили корневого `<div>` |
+|---|---|
+| `entering` | `height: <scrollHeight>`, `overflow: hidden` |
+| `entered` | — (высота отпускается в `auto`) |
+| `exiting` | `height: 0`, `overflow: hidden` |
+| `exited` | `height: 0`, `overflow: hidden`, `visibility: hidden` |
+| `unmounted` | — |
+
+- **Разворачивание.** В `onEnter` измеряется `scrollHeight` контента и
+  записывается в карту стилей фазы `entering` — до того, как `Transition`
+  отрисует эту фазу. Без этого анимировать не от чего.
+- **Сворачивание.** В `onExit` текущая высота фиксируется прямой записью в
+  `node.style.height` (вместо `auto`), затем принудительно читается
+  `scrollHeight` для reflow — иначе браузер схлопнет переход в один кадр.
+- **`entered` без высоты** — контент может свободно менять размер, пока блок
+  раскрыт.
+
+### `transitionProps` — порядок применения
+
+`transitionProps` разливается в `Transition` **после** `in`, `timeout` и
+`nodeRef`, но **до** обработчиков. Практические следствия:
+
+- `in`, `timeout`, `nodeRef` из `transitionProps` **перекроют** внутренние
+  значения. Передача своего `nodeRef` ломает измерение высоты — не делать.
+- `onEnter` / `onEntered` / `onExit` / `onExited` перекрыть нельзя: компонент
+  ставит свои обработчики последними и вызывает пользовательские внутри них,
+  после `onStart` / `onEnd`.
+- Остальные обработчики (`onEntering`, `onExiting`) проходят насквозь без
+  обёртки.
+
+**Известное неудобство типизации:** `transitionProps` типизирован полным
+`ComponentProps<typeof Transition<HTMLDivElement>>`, где `children` и `timeout`
+обязательны. Передать объект с одними обработчиками без каста нельзя, хотя
+`children` / `in` / `timeout` компонент задаёт сам. Сузить тип (например до
+`Partial<>` или `Omit<>`) — breaking change публичного API, отдельное решение
+мейнтейнера.
 
-**Последовательность:**
-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` паттерном
+Токенов нет. `ExpandAnimation.module.less` содержит один класс без
+CSS-переменных:
 
-```tsx
-<Transition in={expanded} timeout={animationTime} nodeRef={nodeRef} ...>
+```text
+.expandAnimation {
+    transition-property: height;
+    transition-timing-function: ease-in-out;
+}
 ```
 
-`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'ов.
+- **`forwardRef` на компоненте — не убирать.** Ref идёт на корневой `<div>`,
+  тот же элемент, что получает `className`, `style` и `...rest`.
+- **Внутренний `nodeRef` и пользовательский `ref` совмещаются в `setRef`.**
+  `nodeRef` нужен `Transition` (React 18 StrictMode-safe вместо
+  `findDOMNode`) и используется для измерения высоты. Убрать совмещение —
+  сломать либо анимацию, либо ref потребителя.
+- **Карта стилей фаз живёт в `useRef`, а не пересоздаётся на рендере.**
+  `onEnter` мутирует `entering.height` до рендера фазы `entering`; на свежем
+  объекте мутация потерялась бы, и раскрытие анимировалось бы от нуля к нулю.
+- **`animationTime` управляет и `timeout`, и `transition-duration`.**
+  Рассинхрон приведёт к тому, что `onEnd` сработает не в конце анимации.
+- **`visibility: hidden` в фазе `exited`** — свёрнутое содержимое не попадает
+  в порядок обхода по Tab. Убирать нельзя: на это опираются потребители —
+  например, `CollapsibleTree-ai.md` фиксирует это как гарантию доступности
+  свёрнутой ветки.
+- **Публичные экспорты barrel** (`src/components/ExpandAnimation/index.ts`):
+  `ExpandAnimation`, `IExpandAnimationProps`. Переименование — breaking change.
+- **`displayName = "ExpandAnimation"`.**
+- **Корневой DOM — `<div>`.** Тег не настраивается.
+- **React 17-совместимость.** Компонент уходит в ветку `release-0`; React
+  18-only API (`useId`, `useSyncExternalStore`, `useInsertionEffect`)
+  использовать нельзя.
 
-**Порядок:** наш handler → (onStart для start-ветки) → user's onEnter/Exit.
+---
 
-### `style` inline — слияние трёх источников
+## Accessibility
 
-```tsx
-style={{
-    transitionDuration: animationTime + "ms",
-    ...transitionStylesRef.current[state],
-    ...style,
-}}
-```
+Компонент **не выставляет ARIA-атрибутов сам** — он не знает, что за контент
+оборачивает и какой элемент им управляет. Связывание с триггером —
+ответственность потребителя:
 
-**Порядок:** дефолт duration → наш state-style → пользовательский
-`style`. Пользовательский стиль побеждает — он может подрезать
-наше поведение, если потребитель этого хочет.
+- `aria-expanded` ставится на кнопку-триггер, не на блок анимации.
+- `aria-controls` на триггере указывает на `id` блока анимации; сам `id`
+  передаётся в `ExpandAnimation` через `...rest`.
+- `role="region"` и `aria-labelledby` при необходимости тоже передаются через
+  `...rest` (так делает `IslandAccordion`).
 
-### `setRef` — double-duty ref
+Что компонент обеспечивает сам: в свёрнутом состоянии (`exited`) корневой блок
+получает `visibility: hidden`, поэтому скрытое содержимое не фокусируется по
+Tab и не читается скринридером. Во время анимации сворачивания
+(`exiting`) `visibility` ещё не выставлен — содержимое кратковременно доступно,
+это осознанный компромисс ради видимого перехода.
 
-```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"`).
+- `AccordionBase` (`src/components/AccordionBase`) — слой выше: хранит
+  состояние раскрытия (controlled / uncontrolled), генерирует id и
+  ARIA-атрибуты для связки header ↔ body, рендерит `ExpandAnimation` внутри.
+  Если нужен аккордеон, а не просто анимация высоты — начинай с него.
+- Потребители внутри библиотеки, чьё поведение зависит от этого компонента:
+  `IslandAccordion` (передаёт `transitionProps`, `role="region"`, `id`),
+  `IslandWidget` и `IslandWidgetExtraFooter`, `CollapsibleTreeExtended`
+  (через `AccordionBase`), `Table/TableBasicSettings`. Правки в фазах анимации
+  и в `onStart` / `onEnd` нужно сверять с ними.
 
 ---
 
-## Инварианты
+## Stories
+
+Основные истории: `stories/ExpandAnimation/ExpandAnimation.stories.tsx`
+Файлы примеров: `stories/ExpandAnimation/examples/`
 
-- **`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`** — есть.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `expanded` и `animationTime` |
+| `Default` | `Default.tsx` | Управляемое раскрытие кнопкой со связкой `aria-expanded` / `aria-controls` |
+| `Animation time` | `AnimationTime.tsx` | Длительности 100 / 300 / 1000 мс |
+| `Callbacks` | `Callbacks.tsx` | `onStart` / `onEnd` как индикатор идущей анимации |
 
 ---
 
-## Accessibility
+## История изменений
 
-- **`visibility: hidden` в свёрнутом состоянии** — убирает элементы
-  из tab-order и screen reader'а. Важный инвариант для "раскрытые
-  элементы не доступны клавиатурой".
-- **`overflow: hidden`** в анимации — скрывает частично видимый
-  контент.
-- **`aria-expanded`** — **не** проставляется ExpandAnimation. Это
-  задача потребителя (AccordionBase делает это).
-- **`onStart`/`onEnd`** — позволяют потребителю обновить ARIA-state
-  в правильный момент (например, объявить "свернуто" для screen
-  reader'а после завершения).
+| Дата | Изменение |
+|---|---|
+| 2026-08-21 | Создан документ. Зафиксированы: карта стилей по фазам анимации, требование хранить её в ref, порядок применения `transitionProps`, контракт `visibility: hidden` в `exited`, отсутствие собственных ARIA-атрибутов и токенов |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-**Нет.** Чистая инфраструктура анимации.
+### Default
 
----
+`stories/ExpandAnimation/examples/Default.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { Button, EButtonTheme, EComponentSize, ETextSize, ExpandAnimation, Text } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [expanded, setExpanded] = useState(true);
+
+    return (
+        <div style={{ maxWidth: 480 }}>
+            <Button
+                theme={EButtonTheme.SECONDARY}
+                size={EComponentSize.MD}
+                aria-expanded={expanded}
+                aria-controls="expand-animation-default"
+                onClick={() => setExpanded((prev) => !prev)}
+            >
+                {expanded ? "Свернуть" : "Развернуть"}
+            </Button>
+
+            <ExpandAnimation id="expand-animation-default" expanded={expanded}>
+                <Text tag="div" size={ETextSize.B1} style={{ paddingTop: 16 }}>
+                    Содержимое разворачивается и сворачивается по высоте. В свёрнутом состоянии блок скрыт через
+                    visibility, поэтому не получает фокус по Tab.
+                </Text>
+            </ExpandAnimation>
+        </div>
+    );
+};
+```
 
-- `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` — внешняя зависимость.
+### Animation time
 
----
+`stories/ExpandAnimation/examples/AnimationTime.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { Button, EButtonTheme, EComponentSize, ETextSize, ExpandAnimation, Text } from "@sberbusiness/triplex-next";
+
+const ANIMATION_TIMES = [100, 300, 1000];
+
+interface IAnimationTimeItemProps {
+    animationTime: number;
+}
+
+const AnimationTimeItem = ({ animationTime }: IAnimationTimeItemProps) => {
+    const [expanded, setExpanded] = useState(true);
+    const contentId = `expand-animation-time-${animationTime}`;
+
+    return (
+        <div style={{ maxWidth: 480 }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{animationTime} мс</div>
+
+            <Button
+                theme={EButtonTheme.SECONDARY}
+                size={EComponentSize.MD}
+                aria-expanded={expanded}
+                aria-controls={contentId}
+                onClick={() => setExpanded((prev) => !prev)}
+            >
+                {expanded ? "Свернуть" : "Развернуть"}
+            </Button>
+
+            <ExpandAnimation id={contentId} expanded={expanded} animationTime={animationTime}>
+                <Text tag="div" size={ETextSize.B1} style={{ paddingTop: 16 }}>
+                    Скорость раскрытия задаётся свойством animationTime.
+                </Text>
+            </ExpandAnimation>
+        </div>
+    );
+};
 
-**Нет собственных stories.** Инфраструктурный компонент. Видно в
-действии через AccordionBase/Spoiler/IslandAccordion stories.
+export const AnimationTime = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        {ANIMATION_TIMES.map((animationTime) => (
+            <AnimationTimeItem key={animationTime} animationTime={animationTime} />
+        ))}
+    </div>
+);
+```
 
----
+### Callbacks
 
-## История изменений
+`stories/ExpandAnimation/examples/Callbacks.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Button, EButtonTheme, EComponentSize, ETextSize, ExpandAnimation, Text } from "@sberbusiness/triplex-next";
+
+export const Callbacks = () => {
+    const [expanded, setExpanded] = useState(true);
+    const [animating, setAnimating] = useState(false);
+
+    return (
+        <div style={{ maxWidth: 480 }}>
+            <Button
+                theme={EButtonTheme.SECONDARY}
+                size={EComponentSize.MD}
+                aria-expanded={expanded}
+                aria-controls="expand-animation-callbacks"
+                onClick={() => setExpanded((prev) => !prev)}
+            >
+                {expanded ? "Свернуть" : "Развернуть"}
+            </Button>
+
+            <Text tag="div" size={ETextSize.B1} style={{ paddingTop: 8 }}>
+                Состояние: {animating ? "анимация идёт" : "анимация завершена"}
+            </Text>
+
+            <ExpandAnimation
+                id="expand-animation-callbacks"
+                expanded={expanded}
+                onStart={() => setAnimating(true)}
+                onEnd={() => setAnimating(false)}
+            >
+                <Text tag="div" size={ETextSize.B1} style={{ paddingTop: 16 }}>
+                    onStart вызывается в начале анимации, onEnd — в конце. Оба коллбэка срабатывают и при
+                    разворачивании, и при сворачивании.
+                </Text>
+            </ExpandAnimation>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |