@sberbusiness/triplex-next-mcp-server 1.40.0-beta → 1.41.0-beta

package/bundle/components/Island.md

@@ -1,9 +1,7 @@
 ---
 component: Island
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [IslandAccordion, IslandWidget, Card, Page]
+related: [IslandAccordion, IslandWidget, BodyPage, HeaderPage, FooterPage, Confirm, ModalWindowBody]
 tokens:
   - --triplex-next-Island-Type1_Background
   - --triplex-next-Island-Type1_Shadow
@@ -19,179 +17,273 @@ version: "1.0"
 
 ## Назначение
 
-Карточка-"остров" — контейнер со скруглениями, фоном и тенью. **Compound-компонент**
-с тремя дочерними слотами: `Island.Header`, `Island.Body`, `Island.Footer`.
-Имеет три визуальных типа (`TYPE_1` / `TYPE_2` / `TYPE_3`) — отличаются
-цветом фона и тенью — и три размера (`SM`/`MD`/`LG`) — отличаются
-радиусом, padding'ом и межблочным margin'ом.
+Базовый контейнер-карточка библиотеки: `<div>` с фоном, тенью, скруглением и внутренними
+отступами. Собственной логики не имеет — задаёт поверхность, на которой лежит контент, и
+вертикальные отступы между своими частями `Island.Header`, `Island.Body`, `Island.Footer`.
 
-Используй когда: нужна базовая карточка с заголовком, контентом и футером.
-Для аккордеона предпочитай `IslandAccordion`, для виджета с иконкой —
-`IslandWidget`.
+Используй когда: контент нужно визуально выделить карточкой на фоне страницы — блок страницы
+(`BodyPage`, `HeaderPage`, `FooterPage`), диалог подтверждения (`Confirm`), элемент аккордеона
+(`IslandAccordion`), виджет (`IslandWidget`).
 
----
-
-## Файловая структура
-
-```text
-src/components/Island/
-├── Island.tsx                   # Object.assign → Body/Header/Footer
-├── enums.ts                     # EIslandType (TYPE_1/TYPE_2/TYPE_3)
-├── utils.ts                     # mapTypeToClassName(type) → styles.type1/2/3
-├── index.ts                     # Barrel
-├── components/
-│   ├── IslandHeader.tsx         # <div .islandHeader>
-│   ├── IslandBody.tsx           # <div .islandBody>
-│   └── IslandFooter.tsx         # <div .islandFooter>
-└── styles/
-    ├── Island.module.less       # Типы, размеры, mobile-ресайз
-    ├── IslandHeader.module.less
-    ├── IslandBody.module.less
-    └── IslandFooter.module.less
-```
+Не используй когда:
+- Нужна интерактивность (клик по карточке, раскрытие, удаление) — Island не кнопка и не
+  управляет состоянием. Возьми `IslandAccordion` (раскрывающиеся элементы) или `IslandWidget`
+  (виджет со сворачиванием в адаптиве), либо положи интерактивный элемент внутрь Island.
+- Нужен только отступ или сетка без визуальной карточки — возьми `Gap`, `Row`/`Col`.
+- Нужен overlay/модальное окно — возьми `ModalWindow`, `LightBox`, `LightBoxSideOverlay`.
 
 ---
 
-## Compound-структура
+## Варианты и props
 
-```tsx
-<Island type={EIslandType.TYPE_1} size={EComponentSize.MD}>
-    <Island.Header>Заголовок</Island.Header>
-    <Island.Body>Основной контент</Island.Body>
-    <Island.Footer>
-        <Button>Действие</Button>
-    </Island.Footer>
-</Island>
-```
+### Обязательные props
 
-Все три слота опциональны. Отступы между ними задаются смежным CSS-селектором
-на корне:
-```less
-.islandHeader + .islandBody,
-.islandHeader + .islandFooter,
-.islandBody + .islandFooter { margin-top: <size>; }
-```
-Размер зазора меняется со `size` (8/12/16 px).
+Обязательных props нет — `<Island>` рендерится с типом `TYPE_1` и размером `MD`.
 
----
+### Опциональные props
 
-## Варианты и props
-
-### Island — `IIslandProps extends HTMLAttributes<HTMLDivElement>`
-
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `type` | `EIslandType` | `TYPE_1` | Визуальный тип (цвет фона + тень). |
-| `size` | `EComponentSize` | `MD` | Размер — влияет на padding и border-radius. |
-| `className`, `style`, `...HTMLDivAttributes` | — | — | Стандартные. |
+| `type` | `EIslandType` | `EIslandType.TYPE_1` | Визуальный тип. Влияет только на фон и тень, на размеры — нет |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Скругление, внутренние отступы карточки и отступы между Header / Body / Footer |
 
-### EIslandType
-
-| Значение | Токены |
-|---|---|
-| `TYPE_1` | `--triplex-next-Island-Type1_Background` + `Type1_Shadow` |
-| `TYPE_2` | `...Type2...` |
-| `TYPE_3` | `...Type3...` |
+Компонент расширяет `React.HTMLAttributes<HTMLDivElement>` — все стандартные атрибуты `<div>`
+(`className`, `style`, `role`, `aria-*`, `data-*`, обработчики событий) попадают на корневой элемент.
 
 ### Размеры
 
-| Size | Desktop (≥ sm+1) | Mobile (≤ @screen-sm-max) | Gap между слотами |
-|---|---|---|---|
-| `SM` | radius 16, padding 16 | radius 16, padding 16 | 8 |
-| `MD` | radius 24, padding 24 | radius 16, padding 16 | 12 |
-| `LG` | radius 32, padding 32 | radius 24, padding 24 | 16 |
-
-На mobile `MD` уменьшается до SM-параметров; `LG` — до размеров близких к MD. Это сохранить при добавлении новых размеров.
+| `size` | `border-radius` | `padding` | Отступ между частями | Адаптив (`max-width: @screen-sm-max`) |
+|---|---|---|---|---|
+| `SM` | 16px | 16px | 8px | без изменений |
+| `MD` | 24px | 24px | 12px | схлопывается до 16px / 16px |
+| `LG` | 32px | 32px | 16px | схлопывается до 24px / 24px |
+
+Отступ между частями схлопыванию в адаптиве не подвергается — меняются только скругление и padding.
+
+### Составные части
+
+`Island.Header`, `Island.Body`, `Island.Footer` (они же `IslandHeader`, `IslandBody`,
+`IslandFooter` из barrel) — тривиальные `<div>`-обёртки: `className + ...rest + forwardRef`,
+собственных props нет. Их единственная задача — нести класс, по которому Island расставляет
+вертикальные отступы. Использовать их все необязательно: у карточки может быть только Body.
+
+### Ограничения
+
+- **Части должны идти соседними элементами в порядке Header → Body → Footer.**
+  Отступы задаются смежными селекторами (`.islandHeader + .islandBody`,
+  `.islandHeader + .islandFooter`, `.islandBody + .islandFooter`) внутри классов размера.
+  Обёртка вокруг части, чужой элемент между частями или другой порядок ломают отступы.
+  Пример из библиотеки: `IslandAccordion` оборачивает `Island.Body` и `Island.Footer` в
+  `ExpandAnimation`, поэтому `.islandHeader + .islandBody` там не срабатывает и отступ между
+  шапкой и телом задаётся собственными паддингами аккордеона; тело и подвал при этом остаются
+  соседями внутри одной обёртки, так что `.islandBody + .islandFooter` сработал бы — аккордеон
+  гасит его явно (`margin-top: 0 !important` у `.footer` в `IslandAccordion.module.less`),
+  потому что владеет своей схемой отступов.
+- **Отступы даёт только родительский Island.** Отрендеренный отдельно `IslandBody` — просто `<div>`.
+- **`className`, переданный в часть, дополняет базовый класс, а не заменяет его** (с 1.41.0).
+  Часть остаётся под селекторами отступов Island и сохраняет `position: relative` из своего
+  LESS-модуля. Потребителю, которому нужна собственная вёрстка внутри карточки, придётся гасить
+  `margin-top` с достаточной специфичностью: правило Island — четыре класса
+  (`.island.md .islandBody + .islandFooter`), поэтому в самой библиотеке для этого используется
+  `!important` (см. `IslandAccordion.module.less`), а не цепочка селекторов.
+- **Вложенный Island:** правила отступов написаны через потомка (`.island.md .islandHeader + .islandBody`),
+  поэтому части вложенной карточки попадают и под селекторы внешней. Специфичность у правил всех
+  размеров одинаковая, так что при разных `size` побеждает правило, которое ниже в
+  `Island.module.less` (порядок в файле — `sm` → `md` → `lg`), а не ближайший родитель.
 
-### Дочерние — `IIslandHeaderProps`, `IIslandBodyProps`, `IIslandFooterProps`
+---
 
-Все extends `React.HTMLProps<HTMLDivElement>` (не `HTMLAttributes` — заметь разницу: `HTMLProps` шире, включает DOM-специфичные проп'ы вроде `form`, `crossOrigin`). Интерфейсы пустые, просто именованные alias'ы.
+## Дизайн-токены
 
-`IslandBody` merge'ит `className` через `clsx` — можно передавать свой класс.
+```
+--triplex-next-Island-Type1_Background
+--triplex-next-Island-Type1_Shadow
+--triplex-next-Island-Type2_Background
+--triplex-next-Island-Type2_Shadow
+--triplex-next-Island-Type3_Background
+--triplex-next-Island-Type3_Shadow
+```
 
-**`IslandHeader` / `IslandFooter`** — НЕ merge'ят `className` из props (баг-или-легаси): `clsx(styles.islandHeader)` без пропагации `className`. **Если нужно передать свой класс — исправляй компонент.** Не полагайся на это поведение.
+Значения задаются в `src/components/DesignTokens/components/Island.ts`. `Type1_Shadow` и
+`Type3_Shadow` — `none`, `Type2_Shadow` — внутренняя рамка `0 0 0 1px … inset`. Скругления и
+отступы токенами не описываются, они заданы литералами в `styles/Island.module.less`.
 
 ---
 
-## Ключевые особенности реализации
+## Инварианты
 
-### Compound через `Object.assign`
+- **`forwardRef`** — обязателен у `Island` и всех трёх частей, `ref` идёт на корневой `<div>`.
+- **Корневой элемент — `<div>`** у Island и у каждой части. Смена тега меняет дефолтный
+  `display` и семантику, то есть ломает вёрстку потребителей (селекторы отступов
+  класс-базированные и тег не проверяют).
+- **Имена CSS-классов `islandHeader` / `islandBody` / `islandFooter` совпадают в четырёх
+  LESS-модулях намеренно.** `scripts/generate-scoped-name.ts` хеширует класс по
+  `имя папки компонента + имя класса + версия библиотеки`, поэтому `.islandHeader` в
+  `styles/Island.module.less` и в `styles/IslandHeader.module.less` дают один и тот же хеш —
+  на этом и держатся селекторы отступов. Следствия:
+  - файлы частей и их стили нельзя выносить из `src/components/Island/`;
+  - переименовывать класс можно только одновременно во всех модулях, где он встречается.
+- **У классов `.islandHeader` / `.islandBody` / `.islandFooter` должно оставаться хотя бы одно
+  CSS-свойство** (сейчас `position: relative` / `display: block`), иначе класс не попадёт в сборку
+  и отступы перестанут работать. В LESS-файлах об этом есть комментарии — не удаляй.
+- **Публичный API:** `Island`, `IslandHeader`, `IslandBody`, `IslandFooter`, `EIslandType`,
+  `IIslandProps`, `IIslandHeaderProps`, `IIslandBodyProps`, `IIslandFooterProps` экспортируются из
+  `src/components/Island/index.ts`. Значения `EIslandType` — строки `type_1` / `type_2` / `type_3`.
+- **Части типизированы через `React.HTMLProps<HTMLDivElement>`** (не `HTMLAttributes`). Сужение
+  типа — breaking change для потребителей.
+- **`mapTypeToClassName` (`utils.ts`) — внутренняя утилита**, в barrel не экспортируется.
 
-```tsx
-export const Island = Object.assign(
-    React.forwardRef<HTMLDivElement, IIslandProps>(...),
-    { Body: IslandBody, Header: IslandHeader, Footer: IslandFooter },
-);
-```
+---
 
-### Margin между слотами — через смежный селектор
+## Accessibility
 
-Отступы между Header/Body/Footer заданы на корне Island, а не на самих слотах. Это значит:
-- если пропустить Body и написать `<Header /><Footer />` — между ними всё равно сработает `margin-top`.
-- если вставить произвольный контент между слотами — смежный селектор не сработает, и придётся выставлять отступ вручную.
+Island — неинтерактивный контейнер: не выставляет роль, не управляет фокусом и не обрабатывает
+клавиатуру. Всё это задаёт потребитель через spread — например, `Confirm` передаёт
+`role="dialog"` и `aria-modal="true"`, `IslandAccordion` кладёт внутрь `Island.Header` собственную
+`<button>` с `aria-expanded` / `aria-controls`.
 
-### Mobile resize
+Важно: `Island.Header` — это `<div>`, а не заголовок. Если нужен семантический заголовок карточки,
+положи внутрь `Title` с нужным тегом или собственный `<h*>`. Текстовые строки компонент не
+хардкодит (библиотека мультиязычная).
 
-`@media (max-width: @screen-sm-max)` перекрывает padding/radius для всех размеров — карточка визуально уменьшается на мобильных. Это поведение реализует автоматическую адаптивность без дополнительных пропсов.
+---
 
-### `IslandHeader` / `IslandFooter` игнорируют `className`
+## Связанные компоненты
 
-В отличие от `IslandBody`, они не мержат `className`. Это по факту баг/неполная реализация, но изменение может затронуть потребителей — не исправлять без согласования.
+- `IslandHeader` (`components/IslandHeader.tsx`, он же `Island.Header`) — шапка карточки.
+  Тривиальная `<div>`-обёртка без собственных props; отдельного AI.md не имеет.
+- `IslandBody` (`components/IslandBody.tsx`, он же `Island.Body`) — основное содержимое.
+  Тривиальная `<div>`-обёртка без собственных props.
+- `IslandFooter` (`components/IslandFooter.tsx`, он же `Island.Footer`) — подвал карточки.
+  Тривиальная `<div>`-обёртка без собственных props.
+- `IslandAccordion` — строит на Island раскрывающиеся элементы; `IslandAccordionFooter`
+  оборачивает `Island.Footer` и передаёт в него свой `className`.
+- `IslandWidget` — виджет со сворачиванием в адаптиве; использует Island как контейнер, но своими
+  Header / Body / Footer, а не частями Island.
+- `BodyPage`, `HeaderPage`, `FooterPage` — оборачивают контент страницы в Island с `TYPE_1`, если
+  их тип `FIRST`.
+- `Confirm` — диалог подтверждения на Island `TYPE_1` с `Island.Body` внутри.
+- `ModalWindowBody` — тело модального окна; `IModalWindowBodyProps` расширяет `IIslandProps`,
+  поэтому `type` и `size` Island доступны и там.
 
 ---
 
-## Инварианты
+## Stories
+
+Основные истории: `stories/Island/Island.stories.tsx`
+Файлы примеров: `stories/Island/examples/`
 
-- **`EIslandType` значения `TYPE_1`/`TYPE_2`/`TYPE_3`** — публичный API. Не переименовывать.
-- **Compound через `Object.assign`** — `Island.Header`, `Island.Body`, `Island.Footer`. Barrel также экспортирует `IslandHeader`/`IslandBody`/`IslandFooter` напрямую.
-- **Margin-логика через `+`-селектор** — изменение на gap-flex сломает существующие интеграции (padding/layout рассчитаны на margin-top).
-- **`forwardRef`** — на всех четырёх компонентах.
-- **Дефолт `type=TYPE_1`, `size=MD`** — не менять.
-- **`HTMLProps<HTMLDivElement>`** (не `HTMLAttributes`) в интерфейсах слотов — сохранить, если потребитель опирается на расширенные атрибуты.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контроль `type`, `size` и состава (Header / Body / Footer) |
+| `Default` | `DefaultExample.tsx` | Минимальная карточка: Header + Body + Footer |
+| `Types` | `TypesExample.tsx` | Все значения `EIslandType` рядом |
+| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG: скругление, паддинги, отступы между частями |
 
 ---
 
-## Accessibility
+## История изменений
 
-- `<div>`-контейнеры, без ARIA-ролей. Если остров используется как диалог/секция/регион — потребитель передаёт `role` и `aria-label` через `...rest`.
-- `IslandHeader` — не `<header>`/`<h*>`; потребитель сам передаёт нужные семантические теги/заголовки внутрь.
-- Tab-навигация — через интерактивные дети.
+| Дата | Изменение |
+|---|---|
+| 2026-08-04 | Создан документ. AI-рефакторинг: JSDoc на props, значениях `EIslandType` и субкомпонентах, `displayName` у `IslandHeader` / `IslandBody` / `IslandFooter`, unit-тесты на все типы и размеры, части острова и `mapTypeToClassName`. Исправлено: `className` в `IslandHeader` и `IslandFooter` больше не затирает базовый класс компонента; побочный отступ в `IslandAccordion` погашен в стилях аккордеона, вид библиотечных компонентов не изменился. Публичный API не изменён. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-```
---triplex-next-Island-Type1_Background
---triplex-next-Island-Type1_Shadow
---triplex-next-Island-Type2_Background
---triplex-next-Island-Type2_Shadow
---triplex-next-Island-Type3_Background
---triplex-next-Island-Type3_Shadow
-```
+### Default
 
-Размеры (`16/24/32` px) и gap'ы (`8/12/16` px) заданы литералами.
-
----
+`stories/Island/examples/DefaultExample.tsx`
 
-## Связанные компоненты
+```tsx
+import React from "react";
+import { Island, EIslandType, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <div style={{ maxWidth: 360 }}>
+        <Island type={EIslandType.TYPE_1} size={EComponentSize.MD}>
+            <Island.Header>Island Header</Island.Header>
+            <Island.Body>Island Body</Island.Body>
+            <Island.Footer>Island Footer</Island.Footer>
+        </Island>
+    </div>
+);
+```
 
-- `IslandAccordion` — остров с раскрытием (содержит `hoverable` chevron-иконку).
-- `IslandWidget` — остров-виджет с иконкой и действиями.
-- `Card` — другая карточная абстракция (интерактивная, с hover-состояниями).
-- `Page` — типовой контейнер страницы, часто содержит Island'ы.
+### Types
 
----
+`stories/Island/examples/TypesExample.tsx`
 
-## Stories
+```tsx
+import React from "react";
+import { Island, EIslandType } from "@sberbusiness/triplex-next";
+
+export const TypesExample = () => (
+    <div
+        style={{
+            display: "grid",
+            gap: 16,
+            gridTemplateColumns: "repeat(auto-fit, minmax(260px, 1fr))",
+        }}
+    >
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_1</div>
+            <Island type={EIslandType.TYPE_1}>
+                <Island.Header>Header content</Island.Header>
+                <Island.Body>Body content</Island.Body>
+                <Island.Footer>Footer content</Island.Footer>
+            </Island>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_2</div>
+            <Island type={EIslandType.TYPE_2}>
+                <Island.Header>Header content</Island.Header>
+                <Island.Body>Body content</Island.Body>
+                <Island.Footer>Footer content</Island.Footer>
+            </Island>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>TYPE_3</div>
+            <Island type={EIslandType.TYPE_3}>
+                <Island.Header>Header content</Island.Header>
+                <Island.Body>Body content</Island.Body>
+                <Island.Footer>Footer content</Island.Footer>
+            </Island>
+        </div>
+    </div>
+);
+```
 
-`stories/Island/Island.stories.tsx`
-Примеры: `stories/Island/examples/`
+### Sizes
 
----
+`stories/Island/examples/SizesExample.tsx`
 
-## История изменений
+```tsx
+import React from "react";
+import { Island, EIslandType, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const SizesExample = () => (
+    <div
+        style={{
+            display: "grid",
+            gap: 16,
+            gridTemplateColumns: "repeat(auto-fit, minmax(260px, 1fr))",
+        }}
+    >
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+                <Island type={EIslandType.TYPE_1} size={size}>
+                    <Island.Header>Header content</Island.Header>
+                    <Island.Body>Body content</Island.Body>
+                    <Island.Footer>Footer content</Island.Footer>
+                </Island>
+            </div>
+        ))}
+    </div>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |