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

package/bundle/components/IslandWidget.md

@@ -1,10 +1,10 @@
 ---
 component: IslandWidget
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Island, IslandAccordion, ExpandAnimation, MediaWidth]
-tokens: []
+related: [IslandAccordion, Island, ExpandAnimation, Text, Title]
+tokens:
+  - IslandWidget.ExtraFooter_Background
+  - IslandWidget.ExtraFooter_Shadow
 stories: stories/IslandWidget/IslandWidget.stories.tsx
 version: "1.0"
 ---
@@ -13,221 +13,686 @@ version: "1.0"
 
 ## Назначение
 
-Виджет-карточка: как `Island` (TYPE_1, MD), но:
-- Принимает контент через **render-props** (`renderHeader`/`renderBody`/`renderFooter`) — не через children.
-- На **мобиле (≤ SM_MAX) автоматически сворачивает Body+Footer**, заголовок становится кликабельным, рядом появляется chevron.
-- Поддерживает необязательный **`ExtraFooter`** — дополнительный раздел, который открывается/закрывается управляемо (`open` prop), **снаружи** Island'а.
-- Оптимизирован под работу в группе (`IslandWidgetWrapper` — provider для `hasExtraFooter`).
+Виджет — карточка на `Island`, собранная из шапки, тела и подвала, которые задаются
+render-функциями. Отличие от голого `Island` — своя схема отступов по размеру и сворачивание
+контента в адаптиве: на узком экране виден только заголовок, остальное раскрывается по клику
+по шапке.
 
-Используй когда: нужен адаптивный виджет на дашборде/пульте, который
-схлопывается на мобиле. Если адаптивность не нужна — `Island` проще.
+Используй когда: блок дашборда со сгруппированной информацией, набором связанных действий
+или отдельной функциональностью, который на мобильном должен схлопываться в одну строку.
+
+Не используй когда:
+- Нужна просто карточка без сворачивания и без готовой схемы отступов — возьми `Island`.
+- Нужен список раскрывающихся секций, где раскрытием управляет потребитель и оно работает на
+  всех ширинах — возьми `IslandAccordion`. У `IslandWidget` сворачивание есть только в адаптиве
+  и состоянием изнутри не управляется.
+- Нужен overlay или модальное окно — возьми `ModalWindow`, `LightBox`.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/IslandWidget/
-├── IslandWidget.tsx                     # Object.assign с Header/Body/Footer/ExtraFooter
-├── IslandWidgetContext.tsx              # { adaptive, disableAdaptiveCollapsing, open }
-├── IslandWidgetLayoutContext.tsx        # { hasExtraFooter, setHasExtraFooter }
-├── index.ts                             # Barrel
-├── components/
-│   ├── IslandWidgetHeader.tsx           # FC + статические .Content/.Description, chevron при adaptive
-│   ├── IslandWidgetHeaderContent.tsx
-│   ├── IslandWidgetHeaderDescription.tsx
-│   ├── IslandWidgetBody.tsx             # FC
-│   ├── IslandWidgetFooter.tsx           # FC + статические .Content/.Controls
-│   ├── IslandWidgetFooterContent.tsx
-│   ├── IslandWidgetFooterControls.tsx
-│   ├── IslandWidgetExtraFooter.tsx      # FC, управляемое open (ExpandAnimation)
-│   └── IslandWidgetWrapper.tsx          # forwardRef, Provider IslandWidgetLayoutContext
-└── styles/*.module.less
-```
+### Обязательные props
 
----
+| Prop | Тип | Описание |
+|---|---|---|
+| `renderHeader` | `(props: IIslandWidgetHeaderProps) => React.ReactNode` | Рендер-функция шапки |
+| `renderBody` | `(props: IIslandWidgetBodyProps) => React.ReactNode` | Рендер-функция тела |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `EComponentSize.MD` | Скругление карточки и отступы всех частей виджета |
+| `renderFooter` | `(props: IIslandWidgetFooterProps) => React.ReactNode` | `undefined` | Рендер-функция подвала. Без неё подвал не рендерится |
+| `disableAdaptiveCollapsing` | `boolean` | `false` | Отключает сворачивание контента в адаптиве — контент всегда виден, индикатор раскрытия не рисуется |
+
+Компонент расширяет `React.HTMLAttributes<HTMLDivElement>` — стандартные атрибуты `<div>`
+(`className`, `style`, `role`, `aria-*`, `data-*`, обработчики) попадают на корневой элемент.
+
+### Render-функции, а не children
+
+Части виджета передаются тремя render-функциями. Каждая получает объект props (сейчас пустой)
+и обязана раскрыть его в соответствующую часть — так у частей остаётся канал для props,
+которые виджет может начать прокидывать позже:
 
-## Compound-структура
+```tsx
+<IslandWidget
+    renderHeader={(props) => (
+        <IslandWidget.Header {...props}>
+            <IslandWidget.Header.Title>Заголовок</IslandWidget.Header.Title>
+        </IslandWidget.Header>
+    )}
+    renderBody={(props) => <IslandWidget.Body {...props}>Контент</IslandWidget.Body>}
+/>
+```
+
+`children` виджет **молча отбрасывает**: они попадают в `...rest`, но корневой `<div>` уже имеет
+собственных JSX-детей (`Island`), и они перекрывают `children` из спреда. Ни ошибки, ни
+предупреждения не будет — контент просто не отрисуется. Всё содержимое кладётся через
+render-функции.
+
+### Составные части
+
+| Часть | Barrel-экспорт | Назначение |
+|---|---|---|
+| `IslandWidget.Header` | `IslandWidgetHeader` | Шапка. В адаптиве получает индикатор раскрытия |
+| `IslandWidget.Header.Title` | — | Заголовок (`Title` H3 medium). На десктопе однострочный с многоточием, в адаптиве переносится |
+| `IslandWidget.Header.Description` | `IslandWidgetHeaderDescription` | Описание (`Text`, вторичный цвет). На десктопе прижато вправо, в адаптиве уходит на свою строку |
+| `IslandWidget.Header.Controls` | — | Контролы шапки. Гасит всплытие клика |
+| `IslandWidget.Body` | `IslandWidgetBody` | Основное содержимое |
+| `IslandWidget.Footer` | `IslandWidgetFooter` | Подвал |
+| `IslandWidget.Footer.Content` | — | Левая часть подвала, занимает свободное место |
+| `IslandWidget.Footer.Controls` | — | Правая часть подвала. В адаптиве переносится на новую строку и выравнивается влево |
+| `IslandWidget.ExtraFooter` | — | Дополнительный подвал **под** карточкой |
+| — | `IslandWidgetWrapper` | Обёртка виджета и `ExtraFooter` |
+| — | `IslandWidgetHeaderContent` | Обёртка содержимого шапки. К `IslandWidget.Header` не привязана |
+
+Отступы частей берутся из `size` виджета через внутренний контекст — отрендеренная отдельно
+`IslandWidgetBody` получит только `className` без размерного класса.
+
+### Сворачивание в адаптиве
+
+- Адаптив определяется хуком `useMobileView()` — медиа-запрос `max-width: 767px`
+  (`EScreenWidth.SM_MAX`), тот же порог, что у компонента `MobileView`.
+- В адаптиве обработчик клика вешается на обёртку вокруг шапки, а тело и подвал заворачиваются
+  в `ExpandAnimation`. На десктопе обработчика нет и `ExpandAnimation` не используется —
+  контент рендерится напрямую.
+- Начальное состояние раскрытия равно `disableAdaptiveCollapsing`: по умолчанию виджет
+  смонтирован свёрнутым, а с `disableAdaptiveCollapsing={true}` — раскрытым. Значение уходит
+  во внутренний контекст и доходит до разметки: `IslandWidgetHeader` вешает класс `open`
+  безусловно, без оглядки на `adaptive`, поэтому при `disableAdaptiveCollapsing={true}` шапка
+  получает этот класс сразу и на десктопе тоже. Видимого эффекта нет — единственное правило на
+  `.open` живёт внутри `@media (max-width: @screen-sm-max)` и вращает каретку, которой в этом
+  режиме не существует. При рефакторинге шапки на это рассчитывать нельзя.
+- Обработчик клика по шапке навешивается по `expandableContent`, то есть только когда
+  сворачивание реально доступно. При `disableAdaptiveCollapsing={true}` обработчика на шапке
+  нет вовсе, поэтому тап по ней не дёргает `setOpen` и не переключает класс `open`.
+- `disableAdaptiveCollapsing` читается только как начальное значение `useState`, поэтому смена
+  этого prop'а после монтирования не пересчитывает уже накопленное состояние раскрытия —
+  она лишь выключает или включает саму обёртку `ExpandAnimation`.
+- Состояние раскрытия внутреннее: props, чтобы прочитать или задать его снаружи, нет.
+- `IslandWidget.Header.Controls` вызывает `stopPropagation` на клике, поэтому взаимодействие с
+  кнопками и полями в шапке не сворачивает виджет. Любой другой интерактивный элемент,
+  положенный в шапку мимо `Controls`, будет сворачивать виджет по клику.
+
+### ExtraFooter
+
+`ExtraFooter` — не часть карточки: он рендерится **соседом** виджета, а не внутри него.
+Оба должны лежать в общем `IslandWidgetWrapper` — через его контекст `ExtraFooter` сообщает
+виджету, что раскрыт, и виджет рисует под собой тень (`::after` с
+`IslandWidget.ExtraFooter_Shadow`).
 
 ```tsx
 <IslandWidgetWrapper>
-    <IslandWidget
-        renderHeader={(props) => (
-            <IslandWidget.Header {...props}>
-                <IslandWidget.Header.Content>Заголовок</IslandWidget.Header.Content>
-                <IslandWidget.Header.Description>Описание</IslandWidget.Header.Description>
-            </IslandWidget.Header>
-        )}
-        renderBody={(props) => <IslandWidget.Body {...props}>{...}</IslandWidget.Body>}
-        renderFooter={(props) => (
-            <IslandWidget.Footer {...props}>
-                <IslandWidget.Footer.Content>...</IslandWidget.Footer.Content>
-                <IslandWidget.Footer.Controls>
-                    <Button>...</Button>
-                </IslandWidget.Footer.Controls>
-            </IslandWidget.Footer>
-        )}
-    />
-    <IslandWidget.ExtraFooter open={extraOpen}>
-        Дополнительный блок снизу
-    </IslandWidget.ExtraFooter>
+    <IslandWidget renderHeader={renderHeader} renderBody={renderBody} />
+    <IslandWidget.ExtraFooter open={open}>Дополнительный контент</IslandWidget.ExtraFooter>
 </IslandWidgetWrapper>
 ```
 
-`IslandWidgetWrapper` опционален — нужен только если используешь `ExtraFooter`
-(иначе `hasExtraFooter` всегда `false` и стили корня не подстраиваются).
+- `open` — контролируемый prop (по умолчанию `false`), раскрытием управляет потребитель.
+  Раскрытие идёт через `ExpandAnimation`, как и сворачивание виджета в адаптиве.
+- Без `IslandWidgetWrapper` `ExtraFooter` работает, но виджет о нём не узнает: контекст по
+  умолчанию содержит no-op колбэки, тень не появится.
+- `ExtraFooter` подтягивается под карточку отрицательным `margin-top: -24px` и компенсирующим
+  `padding-top`, поэтому визуально выглядит продолжением карточки.
+- Обёртка считает раскрытые подвалы, а не хранит флаг: каждый раскрытый `ExtraFooter`
+  регистрируется в контексте на всё время, пока `open === true`, и снимается с учёта
+  и при закрытии, и при размонтировании. Поэтому условный рендеринг подвала так же
+  корректен, как управление через `open` (тень не залипает), а если в одной обёртке
+  раскрыто несколько подвалов, закрытие или удаление одного не снимает тень, пока
+  открыт хотя бы один. `hasExtraFooter` в контексте — это «счётчик > 0».
+- Если виджету нужна фиксированная высота, задавай её на `IslandWidgetWrapper`, а не на
+  `IslandWidget` (story `Example: ExtraFooter with wrapper height`).
+
+### Размеры
+
+`size` задаёт отступы частей; скругление карточки приходит из `Island` того же размера.
+
+| `size` | Header | Body (горизонтально) | Footer | Адаптив (`max-width: 767px`) |
+|---|---|---|---|---|
+| `SM` | 16px 16px 12px | 16px | 16px | Header 16px, место под индикатор справа |
+| `MD` | 24px 24px 16px | 24px | 24px | Схлопывается до 16px |
+| `LG` | 32px 32px 24px | 32px | 32px | Схлопывается до 24px |
+
+`Island` рендерится с `withoutPaddings={true}` — все внутренние отступы принадлежат частям
+виджета, а не карточке.
+
+Размер описания в шапке зависит и от `size`, и от ширины экрана: на десктопе всегда `B4`,
+в адаптиве — `B4` для `SM` и `B3` для `MD` и `LG`.
 
 ---
 
-## Варианты и props
+## Дизайн-токены
 
-### IslandWidget — `IIslandWidgetProps extends HTMLAttributes<HTMLDivElement>`
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию —
+`src/components/DesignTokens/components/IslandWidget.ts`.
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `renderHeader` | `(props: IIslandWidgetHeaderProps) => ReactNode` | Да | Рендер-функция заголовка. Получает пустой объект — можно использовать `IslandWidget.Header` с любыми child'ами. |
-| `renderBody` | `(props: IIslandWidgetBodyProps) => ReactNode` | Да | Рендер-функция Body. |
-| `renderFooter` | `(props: IIslandWidgetFooterProps) => ReactNode` | Нет | Необязательный Footer. |
-| `disableAdaptiveCollapsing` | `boolean` | Нет (default `false`) | Отключает автоматическое сворачивание на мобиле. При `true` — заголовок некликабельный, chevron не рендерится. |
+```text
+IslandWidget.ExtraFooter_Background
+IslandWidget.ExtraFooter_Shadow
+```
 
-**Почему через render-props, а не children:** IslandWidget оборачивает контент в `ExpandAnimation` на adaptive, и ему нужно знать структуру слотов. Render-props позволяют вставлять слоты именно в нужные места (внутрь/снаружи ExpandAnimation).
+Оба токена относятся к дополнительному подвалу: фон самого `ExtraFooter` и тень, которую
+виджет рисует над ним, когда тот раскрыт. Фон и тень самой карточки — токены `Island`
+(`Island.Type1_Background`, `Island.Type1_Shadow`), виджет их не переопределяет. Скругления
+и отступы токенами не описываются — они заданы литералами в `styles/*.module.less`.
 
-### IslandWidget.Header — `IIslandWidgetHeaderProps extends HTMLAttributes<HTMLDivElement>`
+---
 
-FC (не forwardRef). Не управляемый; читает `IslandWidgetContext` и рендерит chevron если `adaptive && !disableAdaptiveCollapsing`. Имеет статические `.Content` и `.Description`.
+## Инварианты
 
-### IslandWidget.Footer — `IIslandWidgetFooterProps extends HTMLAttributes<HTMLDivElement>`
+- **`forwardRef`** — обязателен у `IslandWidget` и `IslandWidgetWrapper`, `ref` идёт на корневой
+  `<div>`. Части виджета (`Header`, `Body`, `Footer`, `ExtraFooter` и их подчасти) — `React.FC`
+  без `ref`; добавление `forwardRef` частям расширяет API и требует отдельного решения.
+- **Публичный API:** из `src/components/IslandWidget/index.ts` экспортируются `IslandWidget`,
+  `IslandWidgetHeader`, `IslandWidgetHeaderContent`, `IslandWidgetHeaderDescription`,
+  `IslandWidgetBody`, `IslandWidgetFooter`, `IslandWidgetWrapper` и их интерфейсы props
+  (`IIslandWidgetProps`, `IIslandWidgetHeaderProps`, `IIslandWidgetBodyProps`,
+  `IIslandWidgetFooterProps`, `IIslandWidgetWrapperProps`), а также типы
+  `TIslandWidgetHeader` и `TIslandWidgetFooter`.
+- **`IslandWidgetExtraFooter`, `IslandWidgetHeaderTitle`, `IslandWidgetHeaderControls`,
+  `IslandWidgetFooterContent`, `IslandWidgetFooterControls` в barrel не экспортируются** — они
+  доступны только как `IslandWidget.ExtraFooter`, `IslandWidget.Header.Title` и т.д. Это
+  сознательная асимметрия: добавление их в barrel расширит публичный API.
+- **`IslandWidgetContext` и `IslandWidgetLayoutContext` — внутренние**, в barrel не выходят.
+  Их интерфейсы можно менять без breaking change.
+- **Корневой элемент — `<div>`** у виджета, обёртки и всех частей. Смена тега ломает вёрстку
+  потребителей: селекторы отступов класс-базированные, но `display` по умолчанию завязан на тег.
+- **`data-tx` потребитель переопределить не может** — атрибут ставится после `...rest`, как у
+  `Header` и `UnorderedListExtended`.
+- **`renderHeader` / `renderBody` / `renderFooter` вызываются с пустым объектом.** Не удаляй
+  параметр из сигнатуры и не заменяй render-функции на `children` — это breaking change.
+- **`IslandWidgetHeaderContent` не имеет своих стилей:** на элемент попадает только `className`
+  потребителя, раскладку задаёт родительская шапка. Компонент экспортируется из barrel и
+  к `IslandWidget.Header` не привязан. Если понадобится собственное оформление — объявляй
+  класс в `styles/IslandWidgetHeader.module.less` и подключай его явно, а не рассчитывай
+  на ранее ссылавшийся здесь несуществующий `styles.islandWidgetHeaderContent`.
+- **`box-shadow` тени `ExtraFooter` больше не помечен `!important`.** Помета снята: в библиотеке
+  нет ни одного другого правила на `.islandWidgetWithExtraFooter::after`, перебивать было нечего.
+  Возвращать помету не нужно — если тень вдруг начнёт перебиваться, ищи появившееся
+  конкурирующее правило, а не возвращай `!important`.
 
-FC. Имеет статические `.Content` и `.Controls` — типовой паттерн "описание + кнопки".
+---
 
-### IslandWidget.Body — `IIslandWidgetBodyProps`
+## Accessibility
 
-FC, без подслотов.
+Сворачивание в адаптиве **не озвучено и не доступно с клавиатуры**: обработчик клика висит на
+обычном `<div>`-обёртке вокруг шапки, у которой нет ни `role="button"`, ни `tabIndex`, ни
+`aria-expanded` / `aria-controls`. Индикатор раскрытия — декоративная иконка с
+`aria-hidden="true"`. Пользователь клавиатуры и скринридера на мобильной ширине не может
+раскрыть контент.
 
-### IslandWidget.ExtraFooter — `IIslandWidgetExtraFooterProps`
+Обходные пути до исправления:
+- Передать `disableAdaptiveCollapsing`, если содержимое обязано быть доступным на всех ширинах.
+- Положить собственную кнопку раскрытия в `IslandWidget.Header.Controls` нельзя — состояние
+  раскрытия внутреннее и снаружи не управляется.
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `open` | `boolean` | `false` | Управляемое состояние раскрытия. |
+Остальное — на потребителе:
+- `IslandWidget.Header.Title` рендерит `Title` тегом по умолчанию; если карточке нужен
+  семантический заголовок уровня страницы, задай тег через props `Title` или положи свой `<h*>`.
+- Кнопки-иконки в `Header.Controls` требуют собственного `aria-label` — библиотека
+  мультиязычная и текст не хардкодит.
+- Роль и `aria-*` для карточки целиком передаются в `IslandWidget` через `...rest`.
 
-- Оборачивает содержимое в `ExpandAnimation expanded={open}`.
-- В `useEffect` пишет `setHasExtraFooter(open)` в `IslandWidgetLayoutContext` — корневой `IslandWidget` использует этот флаг для корректировки стилей корня (добавляет `.islandWidgetWithExtraFooter`).
+---
 
-### IslandWidgetWrapper
+## Связанные компоненты
 
-ForwardRef. Provider `IslandWidgetLayoutContext`. Нужен только для корректной работы `ExtraFooter`.
+### Альтернативы (в `related`)
 
----
+- `IslandAccordion` — раскрывающиеся секции на `Island`. Путать легко: оба сворачивают контент
+  внутри карточки. Разница — у аккордеона раскрытие работает на всех ширинах и им управляет
+  потребитель, у виджета оно только в адаптиве и состояние внутреннее.
 
-## Ключевые особенности реализации
+### Контракты по рендеру (в `related`)
 
-### Adaptive через `useMatchMedia`
+- `Island` — контейнер, который виджет рендерит внутри себя с `type={EIslandType.TYPE_1}`,
+  `withoutPaddings={true}` и своим `size`. Отсюда берутся фон, тень и скругление карточки.
+  Части `Island` (`Island.Header` / `Body` / `Footer`) виджет **не** использует — у него свои.
+- `ExpandAnimation` — анимация сворачивания. Используется дважды: для контента виджета в
+  адаптиве и внутри `IslandWidget.ExtraFooter`. В свёрнутом состоянии выставляет
+  `visibility: hidden`, поэтому контент не получает фокус по Tab.
+- `Text` — `IslandWidget.Header.Description` рендерится через него (`EFontType.SECONDARY`,
+  размер по `size` и ширине экрана).
+- `Title` — `IslandWidget.Header.Title` рендерится через него (`ETitleSize.H3`,
+  `EFontWeightTitle.MEDIUM`).
 
-```ts
-const adaptive = useMatchMedia(
-    `(max-width: ${EScreenWidth.SM_MAX})`,
-    window.innerWidth <= parseInt(EScreenWidth.SM_MAX),
-);
-```
+### Зависимости без отдельной связи (в `related` не входят)
 
-- Первым аргументом — media query, вторым — initial fallback для SSR-safe значения.
-- `window.innerWidth` вычисляется на этапе рендера — **не SSR-safe** (упадёт на сервере). Потребители в SSR должны оборачивать виджет в `ClientOnly`-паттерн.
+- `MobileView` — виджет использует его хук `useMobileView()`, но сам компонент не рендерит.
+  Порог адаптива у них общий, менять его нужно синхронно.
 
-### Управление открытием — внутреннее `useState`
+### Части виджета (своего AI.md не имеют)
 
-```ts
-const [open, setOpen] = useState(disableAdaptiveCollapsing);
-```
+Все части описаны выше в разделе «Составные части»: `IslandWidgetHeader` с
+`Title` / `Description` / `Controls`, `IslandWidgetBody`, `IslandWidgetFooter` с
+`Content` / `Controls`, `IslandWidgetExtraFooter`, `IslandWidgetWrapper` и
+`IslandWidgetHeaderContent`. Собственных props сверх `className + ...rest` у них нет,
+кроме `open` у `ExtraFooter`.
 
-- Если adaptive не включён — поведение не работает.
-- `open` инициализируется значением `disableAdaptiveCollapsing`: без адаптивного сворачивания виджет открыт всегда (это защита, если `disableAdaptiveCollapsing` меняется рантайм).
-- Нет prop'а `defaultOpen` / `opened` / `onToggle` — открытие полностью неуправляемое.
-- Клик по заголовку → `handleHeaderClick` → `setOpen(!open)`. Срабатывает **только если adaptive**.
+---
 
-### ExpandAnimation оборачивает Body + Footer (но не Header)
+## Stories
 
-```tsx
-{expandableContent
-  ? <ExpandAnimation expanded={open}>{renderContent()}</ExpandAnimation>
-  : <>{renderContent()}</>}
-```
+Основные истории: `stories/IslandWidget/IslandWidget.stories.tsx`
+Файлы примеров: `stories/IslandWidget/examples/`
 
-На desktop (не adaptive) или при `disableAdaptiveCollapsing=true` — без анимации, контент виден сразу.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контроль `disableAdaptiveCollapsing` на виджете с шапкой, телом и подвалом |
+| `Default` | `DefaultExample.tsx` | Полный состав: Header с Title / Controls / Description, Body, Footer |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG: отступы частей и скругление карточки |
+| `WithoutFooter` | `WithoutFooterExample.tsx` | Виджет без `renderFooter` — нижний отступ берёт на себя Body |
+| `WithFooterAndExtraFooter` | `WithFooterAndExtraFooterExample.tsx` | `ExtraFooter` рядом с подвалом внутри `IslandWidgetWrapper`, тень под карточкой |
+| `WithoutFooterAndWithExtraFooter` | `WithoutFooterAndWithExtraFooterExample.tsx` | `ExtraFooter` без подвала |
+| `WithExtraFooterAndIslandWidgetHeight` | `WithExtraFooterAndIslandWidgetHeightExample.tsx` | Фиксированная высота задаётся на `IslandWidgetWrapper` |
 
-### `onClick` на wrapper'е Header'а, а не на Header'е
+Файлы примеров с постфиксом `Example` — локальный legacy-паттерн папки.
 
-```tsx
-<div
-    className={clsx({ [styles.islandWidgetHeaderWrapperAdaptive]: adaptive })}
-    onClick={adaptive ? handleHeaderClick : undefined}
->
-    {renderHeader({})}
-</div>
-```
+---
 
-- Click-target — обёртка, а не сам header. Это упрощает CSS (hover только на adaptive).
-- **Нет `role="button"`/`tabIndex`/keyboard-навигации** на wrapper'е — клик только мышью. Это a11y-gap.
+## История изменений
 
-### `hasExtraFooter` в LayoutContext
+| Дата | Изменение |
+|---|---|
+| 2026-09-09 | Создан документ. AI-рефакторинг: JSDoc на props, частях виджета и внутренних контекстах, unit-тесты на все части, сворачивание в адаптиве, `forwardRef`, `className` и размеры. Исправлено: `className` в `IslandWidget.Footer.Content` и `IslandWidget.Footer.Controls` больше не затирает базовый класс; `data-tx` перенесён после `...rest` и больше не переопределяется потребителем. Публичный API не изменён. |
 
-```tsx
-<div className={clsx(styles.islandWidget, className, {
-    [styles.islandWidgetWithExtraFooter]: hasExtraFooter,
-})}>
-```
+---
 
-Корневой Island меняет стиль (например, нижний радиус), когда снизу есть ExtraFooter. Это делает Wrapper'ом эффективным лишь для пары "IslandWidget + ExtraFooter". Без Wrapper'а контекст дефолтный (`hasExtraFooter=false`).
+## Примеры использования
 
----
+### Default
 
-## Инварианты
+`stories/IslandWidget/examples/DefaultExample.tsx`
 
-- **Render-props API (`renderHeader`/`renderBody`/`renderFooter`)** — публичный контракт. Не заменять на children без миграции потребителей.
-- **Дочерние `Header`/`Body`/`Footer`** — `React.FC` (без forwardRef). Обёртки легковесные, но не прокидывают ref наружу.
-- **`IslandWidgetHeader` / `IslandWidgetFooter`** — статические подкомпоненты через **не Object.assign**, а через `TIslandWidgetHeader = FC & { Content, Description }` + присваивание полей после определения. При изменении сохранить паттерн.
-- **`IslandWidget.Body`** — не экспортируется в barrel прямо (`export * from "./IslandWidgetBody"` в components/index.ts есть, но проверить отдельно потребителей). Проверь экспорт перед изменением.
-- **`useMatchMedia` + `window.innerWidth` на инициализации** — **не SSR-safe**. Не переносить в SSR-контекст без защиты.
-- **Клик-target — wrapper Header'а**. Нет ARIA/keyboard для коллапса — известный a11y-debt.
-- **`Island` хардкожен как `TYPE_1 / MD`** внутри — если нужен другой тип/размер, нужен рефакторинг с пропагацией через props.
-- **`ExtraFooter` требует `IslandWidgetWrapper`** для корректного стиля нижнего радиуса корневого Island.
-- **`ExpandAnimation`** оборачивает только Body+Footer; Header всегда виден.
+```tsx
+import React, { useState } from "react";
+import {
+    IslandWidget,
+    Button,
+    ButtonIcon,
+    EComponentSize,
+    EButtonTheme,
+    Link,
+    Text,
+    ETextSize,
+    EFontType,
+    DateField,
+    EFormFieldStatus,
+} from "@sberbusiness/triplex-next";
+import { SettingsStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
+
+    return (
+        <IslandWidget
+            renderBody={(props) => <IslandWidget.Body {...props}>Content</IslandWidget.Body>}
+            renderFooter={(props) => (
+                <IslandWidget.Footer {...props}>
+                    <IslandWidget.Footer.Content>
+                        <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                            <Link>Link text</Link>
+                        </Text>
+                    </IslandWidget.Footer.Content>
+                    <IslandWidget.Footer.Controls>
+                        <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.SM}>
+                            Button text
+                        </Button>
+                        <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM}>
+                            Button text
+                        </Button>
+                    </IslandWidget.Footer.Controls>
+                </IslandWidget.Footer>
+            )}
+            renderHeader={(props) => (
+                <IslandWidget.Header {...props}>
+                    <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                    <IslandWidget.Header.Controls>
+                        <ButtonIcon>
+                            <SettingsStrokeSrvIcon20 paletteIndex={5} />
+                        </ButtonIcon>
+                        <DateField
+                            value={value}
+                            onChange={setValue}
+                            className="island-widget-date-field"
+                            placeholderMask="дд.мм.гггг"
+                            label="дд.мм.гггг"
+                            invalidDateHint="Указана недоступная для выбора дата."
+                            size={EComponentSize.SM}
+                            status={EFormFieldStatus.DEFAULT}
+                        />
+                    </IslandWidget.Header.Controls>
+                    <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+                </IslandWidget.Header>
+            )}
+        />
+    );
+};
+```
 
----
+### Sizes
 
-## Accessibility
+`stories/IslandWidget/examples/SizesExample.tsx`
 
-- Клик по header'у на мобиле **не доступен с клавиатуры** (нет `tabIndex`/`role="button"`/keyboard handler). Known debt. Для критичных сценариев используйте `disableAdaptiveCollapsing` и навигацию через iOS/Android native.
-- Chevron-иконка — `aria-hidden="true"`, правильно.
-- Нет `aria-expanded`/`aria-controls` на wrapper'е — скринридер не анонсирует состояние. Known debt.
-- Остальное — прокидывается через `...htmlDivAttributes`.
+```tsx
+import React, { useState } from "react";
+import {
+    IslandWidget,
+    Button,
+    ButtonIcon,
+    EComponentSize,
+    EButtonTheme,
+    Link,
+    Text,
+    ETextSize,
+    EFontType,
+    DateField,
+    EFormFieldStatus,
+} from "@sberbusiness/triplex-next";
+import { SettingsStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState("");
+
+    const controlSize = size === EComponentSize.SM ? EComponentSize.SM : EComponentSize.MD;
+
+    return (
+        <IslandWidget
+            size={size}
+            renderBody={(props) => <IslandWidget.Body {...props}>Content</IslandWidget.Body>}
+            renderFooter={(props) => (
+                <IslandWidget.Footer {...props}>
+                    <IslandWidget.Footer.Content>
+                        <Text
+                            tag="div"
+                            size={size === EComponentSize.LG ? ETextSize.B2 : ETextSize.B3}
+                            type={EFontType.SECONDARY}
+                        >
+                            <Link>Link text</Link>
+                        </Text>
+                    </IslandWidget.Footer.Content>
+                    <IslandWidget.Footer.Controls>
+                        <Button theme={EButtonTheme.SECONDARY} size={controlSize}>
+                            Button text
+                        </Button>
+                        <Button theme={EButtonTheme.GENERAL} size={controlSize}>
+                            Button text
+                        </Button>
+                    </IslandWidget.Footer.Controls>
+                </IslandWidget.Footer>
+            )}
+            renderHeader={(props) => (
+                <IslandWidget.Header {...props}>
+                    <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                    <IslandWidget.Header.Controls>
+                        <ButtonIcon>
+                            <SettingsStrokeSrvIcon20 paletteIndex={5} />
+                        </ButtonIcon>
+                        <DateField
+                            value={value}
+                            onChange={setValue}
+                            className="island-widget-date-field"
+                            placeholderMask="дд.мм.гггг"
+                            label="дд.мм.гггг"
+                            invalidDateHint="Указана недоступная для выбора дата."
+                            size={controlSize}
+                            status={EFormFieldStatus.DEFAULT}
+                        />
+                    </IslandWidget.Header.Controls>
+                    <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+                </IslandWidget.Header>
+            )}
+        />
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+                <SizeItem size={size} />
+            </div>
+        ))}
+    </div>
+);
+```
 
----
+### WithoutFooter
 
-## Дизайн-токены
+`stories/IslandWidget/examples/WithoutFooterExample.tsx`
 
-Нет собственных (все от `Island.TYPE_1`: `--triplex-next-Island-Type1_Background` / `_Shadow`).
+```tsx
+import React from "react";
+import { IslandWidget } from "@sberbusiness/triplex-next";
 
----
+export const WithoutFooterExample = () => (
+    <IslandWidget
+        renderBody={(props) => <IslandWidget.Body {...props}>Content</IslandWidget.Body>}
+        renderHeader={(props) => (
+            <IslandWidget.Header {...props}>
+                <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+            </IslandWidget.Header>
+        )}
+    />
+);
+```
 
-## Связанные компоненты
+### WithFooterAndExtraFooter
 
-- `Island` — корневая карточка (hardcoded TYPE_1/MD внутри).
-- `IslandAccordion` — альтернатива для списка раскрывающихся элементов.
-- `ExpandAnimation` — используется для анимации сворачивания.
-- `MediaWidth.useMatchMedia` — детектирует адаптив.
-- `EScreenWidth` (`@sberbusiness/triplex-next/helpers/breakpoints`) — breakpoint SM_MAX.
+`stories/IslandWidget/examples/WithFooterAndExtraFooterExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import {
+    IslandWidget,
+    IslandWidgetWrapper,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Link,
+    Text,
+    ETextSize,
+    EFontType,
+} from "@sberbusiness/triplex-next";
+
+export const WithFooterAndExtraFooterExample = () => {
+    const [extraFooterOpen, setExtraFooterOpen] = useState(false);
+    const [bodyHeight, setBodyHeight] = useState(260);
+
+    const handleExtraFooterOpen = (open: boolean) => {
+        setExtraFooterOpen(open);
+        setBodyHeight(open ? 196 : 260);
+    };
+
+    return (
+        <>
+            <div className="island-widget-control-panel">
+                <Button
+                    theme={EButtonTheme.GENERAL}
+                    size={EComponentSize.SM}
+                    onClick={() => handleExtraFooterOpen(true)}
+                >
+                    Open Extra Footer
+                </Button>
+                <Button
+                    theme={EButtonTheme.GENERAL}
+                    size={EComponentSize.SM}
+                    onClick={() => handleExtraFooterOpen(false)}
+                >
+                    Close Extra Footer
+                </Button>
+            </div>
+
+            <IslandWidgetWrapper>
+                <IslandWidget
+                    renderBody={(props) => (
+                        <IslandWidget.Body {...props}>
+                            <div style={{ height: bodyHeight, transition: "height 0.3s ease-in-out" }}>Content</div>
+                        </IslandWidget.Body>
+                    )}
+                    renderFooter={(props) => (
+                        <IslandWidget.Footer {...props}>
+                            <IslandWidget.Footer.Content>
+                                <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                                    <Link href="#">Link text</Link>
+                                </Text>
+                            </IslandWidget.Footer.Content>
+                            <IslandWidget.Footer.Controls>
+                                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.SM}>
+                                    Button text
+                                </Button>
+                                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM}>
+                                    Button text
+                                </Button>
+                            </IslandWidget.Footer.Controls>
+                        </IslandWidget.Footer>
+                    )}
+                    renderHeader={(props) => (
+                        <IslandWidget.Header {...props}>
+                            <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                            <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+                        </IslandWidget.Header>
+                    )}
+                />
+                <IslandWidget.ExtraFooter open={extraFooterOpen}>
+                    <div className="island-widget-extra-footer">
+                        <Text size={ETextSize.B3}>Extra footer content</Text>
+                    </div>
+                </IslandWidget.ExtraFooter>
+            </IslandWidgetWrapper>
+        </>
+    );
+};
+```
 
-## Stories
+### WithoutFooterAndWithExtraFooter
 
-`stories/IslandWidget/IslandWidget.stories.tsx`
-Примеры: `stories/IslandWidget/examples/`
+`stories/IslandWidget/examples/WithoutFooterAndWithExtraFooterExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import {
+    IslandWidget,
+    IslandWidgetWrapper,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const WithoutFooterAndWithExtraFooterExample = () => {
+    const [extraFooterOpen, setExtraFooterOpen] = useState(false);
+    const [bodyHeight, setBodyHeight] = useState(260);
+
+    const handleExtraFooterOpen = (open: boolean) => {
+        setExtraFooterOpen(open);
+        setBodyHeight(open ? 196 : 260);
+    };
+
+    return (
+        <>
+            <div className="island-widget-control-panel">
+                <Button
+                    theme={EButtonTheme.GENERAL}
+                    size={EComponentSize.SM}
+                    onClick={() => handleExtraFooterOpen(true)}
+                >
+                    Open Extra Footer
+                </Button>
+                <Button
+                    theme={EButtonTheme.GENERAL}
+                    size={EComponentSize.SM}
+                    onClick={() => handleExtraFooterOpen(false)}
+                >
+                    Close Extra Footer
+                </Button>
+            </div>
+
+            <IslandWidgetWrapper>
+                <IslandWidget
+                    renderBody={(props) => (
+                        <IslandWidget.Body {...props}>
+                            <div style={{ height: bodyHeight, transition: "height 0.3s ease-in-out" }}>Content</div>
+                        </IslandWidget.Body>
+                    )}
+                    renderHeader={(props) => (
+                        <IslandWidget.Header {...props}>
+                            <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                            <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+                        </IslandWidget.Header>
+                    )}
+                />
+                <IslandWidget.ExtraFooter open={extraFooterOpen}>
+                    <div className="island-widget-extra-footer">
+                        <Text size={ETextSize.B3}>Extra footer content</Text>
+                    </div>
+                </IslandWidget.ExtraFooter>
+            </IslandWidgetWrapper>
+        </>
+    );
+};
+```
 
-## История изменений
+### WithExtraFooterAndIslandWidgetHeight
+
+`stories/IslandWidget/examples/WithExtraFooterAndIslandWidgetHeightExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    IslandWidget,
+    IslandWidgetWrapper,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Text,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+
+export const WithExtraFooterAndIslandWidgetHeightExample = () => {
+    const [extraFooterOpen, setExtraFooterOpen] = useState(false);
+
+    return (
+        <>
+            <div className="island-widget-control-panel">
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM} onClick={() => setExtraFooterOpen(true)}>
+                    Open Extra Footer
+                </Button>
+                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM} onClick={() => setExtraFooterOpen(false)}>
+                    Close Extra Footer
+                </Button>
+            </div>
+
+            <IslandWidgetWrapper style={{ height: "500px" }}>
+                <IslandWidget
+                    renderBody={(props) => <IslandWidget.Body {...props}>Content</IslandWidget.Body>}
+                    renderHeader={(props) => (
+                        <IslandWidget.Header {...props}>
+                            <IslandWidget.Header.Title>Title</IslandWidget.Header.Title>
+                            <IslandWidget.Header.Description>Description</IslandWidget.Header.Description>
+                        </IslandWidget.Header>
+                    )}
+                />
+                <IslandWidget.ExtraFooter open={extraFooterOpen}>
+                    <div className="island-widget-extra-footer">
+                        <Text size={ETextSize.B3}>Extra footer content</Text>
+                    </div>
+                </IslandWidget.ExtraFooter>
+            </IslandWidgetWrapper>
+        </>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |