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

package/bundle/components/Spoiler.md

@@ -1,9 +1,7 @@
 ---
 component: Spoiler
-category: Disclosure
-figma-node: ""
-figma-file: ""
-related: [AccordionBase, Button]
+category: Spoiler
+related: [IslandAccordion, Button]
 tokens: []
 stories: stories/Spoiler/Spoiler.stories.tsx
 version: "1.0"
@@ -13,104 +11,181 @@ version: "1.0"
 
 ## Назначение
 
-Раскрывающаяся область с link-кнопкой-триггером сверху. Текст триггера
-переключается между `labelExpand` / `labelCollapse`, содержимое скрывается
-CSS-классом (`hidden`) — DOM не размонтируется.
+Кнопка-ссылка с кареткой, по клику раскрывающая блок содержимого под собой. Самый
+лёгкий способ спрятать необязательные детали: собственного оформления у компонента
+почти нет — ни рамки, ни фона, ни отступов вокруг. Кнопку рисует `Button` с темой
+`EButtonTheme.LINK`, содержимое в свёрнутом состоянии просто выключено через
+`display: none`.
 
-Используй когда: нужно показать/скрыть блок вспомогательной информации
-через простой inline-триггер (не секцию-«аккордеон»).
-Не используй когда: нужна секционированная навигация с несколькими
-панелями — используй `AccordionBase`.
+Используй когда: рядом с основным контентом нужно спрятать пояснение, подробности
+операции, «показать ещё» — и хочется, чтобы блок не выглядел отдельной секцией.
 
----
-
-## Файловая структура
+Не используй когда:
 
-```text
-src/components/Spoiler/
-├── Spoiler.tsx       # forwardRef<HTMLDivElement, TSpoilerProps>
-├── index.ts
-└── styles/Spoiler.module.less
-```
+- нужен аккордеон как самостоятельная секция страницы — с фоном, разделителями,
+  несколькими элементами и одновременным закрытием соседей: это `IslandAccordion`;
+- нужна плавная анимация раскрытия по высоте: `Spoiler` переключает содержимое
+  мгновенно, анимирована только каретка. Анимация высоты — `ExpandAnimation` плюс
+  своя кнопка;
+- нужен спойлер внутри `AlertProcess` — там своя реализация `AlertProcess.Spoiler`,
+  связанная с родителем через контекст.
 
 ---
 
 ## Варианты и props
 
-`TSpoilerProps = ISpoilerControlledProps | ISpoilerUncontrolledProps`.
-
-### Общие (`ISpoilerBaseProps`)
+`ISpoilerBaseProps` расширяет `React.HTMLAttributes<HTMLDivElement>` — `...rest`
+уходит на корневой `<div>`.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `labelExpand` | `string` | — | Текст кнопки в свернутом состоянии. |
-| `labelCollapse?` | `string` | — | Текст кнопки в раскрытом состоянии. Если не задан — кнопка показывает `labelExpand` всегда. |
-| `onToggle?` | `(expanded: boolean) => void` | — | Колбэк изменения состояния. Вызывается ВСЕГДА (и в controlled, и в uncontrolled). |
-| `rightBlock?` | `ReactNode` | — | Доп. контент справа от триггера в шапке. |
-| `size?` | `EComponentSize` | `MD` | `SM` → icon-16, `MD`/`LG` → icon-20. |
-| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корень. |
-
-### Controlled (`ISpoilerControlledProps`)
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `expanded` | `boolean` | Контролируемое состояние. |
-| `toggle` | `(next: boolean) => void` | Контролирующий handler. Обязателен если передан `expanded`. |
+| `labelExpand` | `string` | Текст кнопки в свёрнутом состоянии |
 
-### Uncontrolled (`ISpoilerUncontrolledProps`)
+### Опциональные props
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `expanded` | `never` | Запрещено. |
-| `toggle` | `never` | Запрещено. |
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `labelCollapse` | `string` | — | Текст кнопки в раскрытом состоянии. Не передан — в раскрытом состоянии у кнопки остаётся одна каретка без текста, кнопка теряет доступное имя. Передавать стоит всегда |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер: уходит в `Button` (у темы `LINK` от размера зависит только типографика — `font-size` и `line-height`, высота и отступы не задаются) и выбирает каретку — 16px для `SM`, 20px для `MD` и `LG` |
+| `onToggle` | `(expanded: boolean) => void` | — | Уведомление о клике по кнопке. Вызывается в **обоих** режимах и получает следующее состояние |
+| `rightBlock` | `React.ReactNode` | — | Содержимое правой части заголовка |
+| `children` | `React.ReactNode` | — | Раскрываемое содержимое |
+| `className` | `string` | — | Мерджится с собственными классами корневого `<div>` через `clsx` |
+
+### Два режима: контролируемый и неконтролируемый
 
-Различение controlled/uncontrolled — по `expanded !== undefined` внутри компонента.
+`TSpoilerProps` — discriminated union по наличию `expanded`
+(`ISpoilerControlledProps | ISpoilerUncontrolledProps`):
+
+| Режим | Признак | Кто хранит состояние | Что происходит по клику |
+|---|---|---|---|
+| Неконтролируемый | `expanded` не передан | компонент (`useState`) | состояние переключается внутри, вызывается `onToggle(next)` |
+| Контролируемый | передан `expanded` + `toggle` | потребитель | вызывается `toggle(next)` и `onToggle(next)`, вид не меняется до обновления `expanded` |
+
+- В контролируемом режиме `toggle` обязателен — без него клик ничего не сделает.
+  Компонент сам `expanded` не меняет.
+- `expanded?: never` / `toggle?: never` в `ISpoilerUncontrolledProps` — это запрет
+  на смешивание режимов на уровне типов, а не props, которые можно передать.
+- Режим вычисляется на каждом рендере (`expanded !== undefined`). Переключать его
+  по ходу жизни компонента не стоит: внутреннее состояние при этом сохраняется от
+  прошлого неконтролируемого периода.
+
+### `rightBlock` — что это на самом деле
+
+Рендерится в заголовке сразу после кнопки, **вне** её: клик по `rightBlock`
+содержимое не раскрывает. Заголовок (`.head`) — обычный блок, а не
+flex-контейнер, поэтому `rightBlock` встаёт в общий инлайн-поток справа от
+кнопки, а не прижимается к правому краю. Снаружи это не лечится: обёртка вокруг
+`Spoiler` управляет раскладкой его корневого элемента, а не содержимого
+заголовка. Прижать `rightBlock` к правому краю можно только раскладкой внутри
+`.head`, то есть правкой самого компонента.
+
+### Известные особенности
+
+Ниже — расхождения реализации с ожиданиями, зафиксированные при AI-рефакторинге
+(TRI-81). Все они видны в текущем коде и **не исправлены**: починка меняет разметку
+или внешний вид, то есть требует отдельного решения мейнтейнера.
+
+- **Отступ содержимого от заголовка не работает.** В `Spoiler.module.less`
+  селекторы `.lg` / `.md` / `.sm` вложены внутрь `.spoiler` как потомки
+  (`.spoiler .lg .content`), а размерный класс навешивается на сам корень
+  `.spoiler`. Поэтому `margin-top` у `.content` (8px / 0 / −4px) не применяется ни
+  при каком размере. Распаковка вложенности изменит вид компонента.
+- **`aria-expanded` отсутствует на первом рендере в неконтролируемом режиме.**
+  Внутреннее состояние инициализируется значением пропа (`useState(expanded)`),
+  то есть `undefined`, и атрибут не попадает в разметку до первого клика.
+  Визуально всё верно (содержимое скрыто), но скринридер не знает, что кнопка
+  управляет раскрытием.
 
 ---
 
-## Иконка
+## Дизайн-токены
 
-| Size | Icon |
-|---|---|
-| `SM` | `CaretdownStrokeSrvIcon16` (paletteIndex=5) |
-| `MD` | `CaretdownStrokeSrvIcon20` (paletteIndex=5) |
-| `LG` | `CaretdownStrokeSrvIcon20` (paletteIndex=5) |
+Своих токенов у компонента нет: `Spoiler.module.less` задаёт только раскладку,
+поворот каретки и перенос текста кнопки, CSS-переменных в нём не встречается.
 
-Поворот иконки — через CSS (`styles.opened` на root применяет transform к `.caretIcon`).
+Цвет, типографика и фокус кнопки приходят из `Button` с темой
+`EButtonTheme.LINK` — переопределяются через её токены (`Button.Link_Color_Default`,
+`Button.Link_Color_Hover`, `Button.Link_Color_Active`, `Button.Link_Shadow_Focus`
+и остальные, см. `Button-ai.md`). Цвет каретки задаёт `paletteIndex={5}` иконки,
+а не токен. Оформление содержимого — полностью на стороне потребителя.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef<HTMLDivElement>`** — не убирать.
-- **Триггер — `Button` с `theme={EButtonTheme.LINK}`** и размером `size` из props. Замена на `ButtonIcon` / `Link` — breaking change.
-- **Контент не размонтируется** при сворачивании — скрывается классом `styles.hidden`. Это сохраняет state детей между раскрытиями; потребитель должен учитывать, что скрытый контент остаётся в DOM (focusability, форм-валидация).
-- **`aria-expanded` на Button, `aria-controls` → id контента, `id` контента** — генерируется через `uniqueId()` один раз в `useRef`. Не переопределять.
-- **`onToggle` вызывается всегда** — даже в controlled варианте (удобно для аналитики рядом с `toggle`).
-- **`labelCollapse` опционален** — если не задан, открытое состояние покажет `labelExpand`. Это допустимо, но нетипично.
+- **`forwardRef` на компоненте — не убирать.** Ref идёт на корневой `<div>`, тот
+  же элемент, что получает `className` и `...rest`.
+- **Корневой DOM — `<div>`** с `data-tx` (версия пакета). Тег не настраивается.
+- **Публичные экспорты barrel** (`src/components/Spoiler/index.ts`): `Spoiler`,
+  `ISpoilerBaseProps`, `ISpoilerControlledProps`, `ISpoilerUncontrolledProps`,
+  `TSpoilerProps`. Переименование — breaking change.
+- **`displayName = "Spoiler"`.**
+- **Кнопку раскрытия рисует `Button` с темой `EButtonTheme.LINK`.** Она же
+  отвечает за визуальное состояние «раскрыто»: `Button` читает переданный
+  `aria-expanded` и по нему навешивает свой класс `expanded` и активное состояние
+  иконки. Убрать `aria-expanded` — значит сломать не только a11y, но и внешний вид.
+- **Связка `aria-controls` → `id` содержимого** держится на `useRef` с
+  `uniqueId()`. Id генерируется один раз на монтирование.
+- **React 17-совместимость.** Компонент уходит в ветку `release-0`, поэтому
+  `useId` и другие React 18-only API использовать нельзя — для уникальных id
+  остаётся `uniqueId()` из `lodash-es`.
+- **Размерные классы `sm` / `md` / `lg` навешиваются на корень** через
+  `createSizeToClassNameMap`. На них опираются unit-тесты.
 
 ---
 
 ## Accessibility
 
-- `aria-expanded={open}` и `aria-controls={instanceId}` связывают триггер-кнопку с контентом.
-- Контент получает `id={instanceId.current}` — уникальный per-instance.
-- Триггер — нативная `<button>` (через `Button` → `theme=LINK`), стандартные keyboard-обработчики (Enter/Space).
-- Скрытый контент остаётся в DOM (не `display:none` → `hidden` класс; точная CSS-имплементация — в `Spoiler.module.less`). Проверь перед изменением, не должен ли контент быть недоступен для screen reader'а.
+- Раскрытием управляет настоящая `<button>` (внутри `Button`), поэтому
+  клавиатура работает штатно: `Tab` — фокус, `Enter` / `Space` — переключение.
+  Собственных клавиатурных обработчиков у компонента нет.
+- `aria-expanded` на кнопке отражает состояние раскрытия. Исключение —
+  первый рендер в неконтролируемом режиме, см. «Известные особенности».
+- `aria-controls` на кнопке указывает на `id` блока содержимого. Id генерируется
+  сам, передавать его снаружи нельзя.
+- Свёрнутое содержимое скрыто через `display: none`, поэтому не попадает ни в
+  порядок обхода по `Tab`, ни в дерево доступности.
+- **Текст кнопки — ответственность потребителя.** Библиотека мультиязычная,
+  компонент ничего не хардкодит. Без `labelCollapse` в раскрытом состоянии у
+  кнопки не остаётся доступного имени — передавай оба текста.
+- `rightBlock` лежит вне кнопки и в её доступное имя не попадает.
 
 ---
 
 ## Связанные компоненты
 
-- `AccordionBase` — многосекционный аккордеон.
-- `Button` — триггер (LINK theme).
+- `IslandAccordion` — альтернатива уровнем выше: раскрываемые секции с фоном,
+  разделителями, анимацией высоты и группировкой нескольких элементов. Если
+  раскрываемый блок должен выглядеть самостоятельной секцией, это он, а не
+  `Spoiler`.
+- `Button` — рендерится внутри как кнопка раскрытия (`EButtonTheme.LINK`,
+  тот же `size`). Отсюда берутся типографика, цвета, hover/active/focus и
+  визуальное состояние «раскрыто» по `aria-expanded`.
+- `ExpandAnimation` — строительный блок для плавного раскрытия по высоте.
+  `Spoiler` его не использует: содержимое переключается мгновенно. Нужна
+  анимация — собирай связку сам или бери `IslandAccordion`.
+- `AlertProcess` — не путать: у него есть собственный `AlertProcess.Spoiler`
+  (`AlertProcessSpoiler`) с похожим названием и другим API (`open` / `onOpen`),
+  живущий только внутри `AlertProcess` и не использующий этот компонент.
 
 ---
 
 ## Stories
 
-`stories/Spoiler/Spoiler.stories.tsx`
-Примеры: `stories/Spoiler/examples/`
+Основные истории: `stories/Spoiler/Spoiler.stories.tsx`
+Файлы примеров: `stories/Spoiler/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `size`, `labelExpand`, `labelCollapse` |
+| `Default` | `Default.tsx` | Минимальный неконтролируемый спойлер |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG с подписями |
+| `With right block` | `WithRightBlock.tsx` | Содержимое правой части заголовка |
+| `Controlled` | `Controlled.tsx` | Контролируемый режим: `expanded` + `toggle` |
+| `VisualTests` | `VisualTests.tsx` | Свёрнутое и раскрытое состояние всех размеров, `rightBlock`, перенос длинного текста кнопки |
 
 ---
 
@@ -118,4 +193,111 @@ src/components/Spoiler/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-25 | Создан документ. Зафиксированы: два режима работы и контракт `toggle`, поведение `rightBlock` в неflex-заголовке, связка `aria-controls` → `id` на `uniqueId`, зависимость визуального состояния «раскрыто» от `aria-expanded` в `Button`, отсутствие своих токенов и две известные особенности (неработающий `margin-top` у содержимого, отсутствие `aria-expanded` на первом неконтролируемом рендере) |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Spoiler/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Spoiler, Text, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Spoiler labelExpand="Развернуть" labelCollapse="Свернуть">
+        <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+            Скрытый контент
+        </Text>
+    </Spoiler>
+);
+```
+
+### Sizes
+
+`stories/Spoiler/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Spoiler, Text, EComponentSize, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+const SIZE_TO_TEXT_SIZE_MAP: Record<EComponentSize, ETextSize> = {
+    [EComponentSize.SM]: ETextSize.B4,
+    [EComponentSize.MD]: ETextSize.B3,
+    [EComponentSize.LG]: ETextSize.B2,
+};
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Spoiler size={size} labelExpand="Развернуть" labelCollapse="Свернуть">
+                    <Text size={SIZE_TO_TEXT_SIZE_MAP[size]} type={EFontType.PRIMARY}>
+                        Скрытый контент
+                    </Text>
+                </Spoiler>
+            </div>
+        ))}
+    </div>
+);
+```
+
+### With right block
+
+`stories/Spoiler/examples/WithRightBlock.tsx`
+
+```tsx
+import React from "react";
+import { Spoiler, Text, EComponentSize, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const WithRightBlock = () => (
+    <Spoiler
+        labelExpand="Развернуть"
+        labelCollapse="Свернуть"
+        size={EComponentSize.MD}
+        rightBlock={
+            <Text size={ETextSize.B3} type={EFontType.SECONDARY}>
+                12 документов
+            </Text>
+        }
+    >
+        <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+            Скрытый контент
+        </Text>
+    </Spoiler>
+);
+```
+
+### Controlled
+
+`stories/Spoiler/examples/Controlled.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Spoiler, Text, EComponentSize, ETextSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Controlled = () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+        <Spoiler
+            expanded={expanded}
+            toggle={setExpanded}
+            labelExpand="Развернуть"
+            labelCollapse="Свернуть"
+            size={EComponentSize.MD}
+        >
+            <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+                Скрытый контент
+            </Text>
+        </Spoiler>
+    );
+};
+```
+