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

package/bundle/components/IslandWidget.md

@@ -0,0 +1,233 @@
+---
+component: IslandWidget
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Island, IslandAccordion, ExpandAnimation, MediaWidth]
+tokens: []
+stories: stories/IslandWidget/IslandWidget.stories.tsx
+version: "1.0"
+---
+
+# IslandWidget
+
+## Назначение
+
+Виджет-карточка: как `Island` (TYPE_1, MD), но:
+- Принимает контент через **render-props** (`renderHeader`/`renderBody`/`renderFooter`) — не через children.
+- На **мобиле (≤ SM_MAX) автоматически сворачивает Body+Footer**, заголовок становится кликабельным, рядом появляется chevron.
+- Поддерживает необязательный **`ExtraFooter`** — дополнительный раздел, который открывается/закрывается управляемо (`open` prop), **снаружи** Island'а.
+- Оптимизирован под работу в группе (`IslandWidgetWrapper` — provider для `hasExtraFooter`).
+
+Используй когда: нужен адаптивный виджет на дашборде/пульте, который
+схлопывается на мобиле. Если адаптивность не нужна — `Island` проще.
+
+---
+
+## Файловая структура
+
+```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
+```
+
+---
+
+## Compound-структура
+
+```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>
+</IslandWidgetWrapper>
+```
+
+`IslandWidgetWrapper` опционален — нужен только если используешь `ExtraFooter`
+(иначе `hasExtraFooter` всегда `false` и стили корня не подстраиваются).
+
+---
+
+## Варианты и props
+
+### IslandWidget — `IIslandWidgetProps extends HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `renderHeader` | `(props: IIslandWidgetHeaderProps) => ReactNode` | Да | Рендер-функция заголовка. Получает пустой объект — можно использовать `IslandWidget.Header` с любыми child'ами. |
+| `renderBody` | `(props: IIslandWidgetBodyProps) => ReactNode` | Да | Рендер-функция Body. |
+| `renderFooter` | `(props: IIslandWidgetFooterProps) => ReactNode` | Нет | Необязательный Footer. |
+| `disableAdaptiveCollapsing` | `boolean` | Нет (default `false`) | Отключает автоматическое сворачивание на мобиле. При `true` — заголовок некликабельный, chevron не рендерится. |
+
+**Почему через render-props, а не children:** IslandWidget оборачивает контент в `ExpandAnimation` на adaptive, и ему нужно знать структуру слотов. Render-props позволяют вставлять слоты именно в нужные места (внутрь/снаружи ExpandAnimation).
+
+### IslandWidget.Header — `IIslandWidgetHeaderProps extends HTMLAttributes<HTMLDivElement>`
+
+FC (не forwardRef). Не управляемый; читает `IslandWidgetContext` и рендерит chevron если `adaptive && !disableAdaptiveCollapsing`. Имеет статические `.Content` и `.Description`.
+
+### IslandWidget.Footer — `IIslandWidgetFooterProps extends HTMLAttributes<HTMLDivElement>`
+
+FC. Имеет статические `.Content` и `.Controls` — типовой паттерн "описание + кнопки".
+
+### IslandWidget.Body — `IIslandWidgetBodyProps`
+
+FC, без подслотов.
+
+### IslandWidget.ExtraFooter — `IIslandWidgetExtraFooterProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `open` | `boolean` | `false` | Управляемое состояние раскрытия. |
+
+- Оборачивает содержимое в `ExpandAnimation expanded={open}`.
+- В `useEffect` пишет `setHasExtraFooter(open)` в `IslandWidgetLayoutContext` — корневой `IslandWidget` использует этот флаг для корректировки стилей корня (добавляет `.islandWidgetWithExtraFooter`).
+
+### IslandWidgetWrapper
+
+ForwardRef. Provider `IslandWidgetLayoutContext`. Нужен только для корректной работы `ExtraFooter`.
+
+---
+
+## Ключевые особенности реализации
+
+### Adaptive через `useMatchMedia`
+
+```ts
+const adaptive = useMatchMedia(
+    `(max-width: ${EScreenWidth.SM_MAX})`,
+    window.innerWidth <= parseInt(EScreenWidth.SM_MAX),
+);
+```
+
+- Первым аргументом — media query, вторым — initial fallback для SSR-safe значения.
+- `window.innerWidth` вычисляется на этапе рендера — **не SSR-safe** (упадёт на сервере). Потребители в SSR должны оборачивать виджет в `ClientOnly`-паттерн.
+
+### Управление открытием — внутреннее `useState`
+
+```ts
+const [open, setOpen] = useState(disableAdaptiveCollapsing);
+```
+
+- Если adaptive не включён — поведение не работает.
+- `open` инициализируется значением `disableAdaptiveCollapsing`: без адаптивного сворачивания виджет открыт всегда (это защита, если `disableAdaptiveCollapsing` меняется рантайм).
+- Нет prop'а `defaultOpen` / `opened` / `onToggle` — открытие полностью неуправляемое.
+- Клик по заголовку → `handleHeaderClick` → `setOpen(!open)`. Срабатывает **только если adaptive**.
+
+### ExpandAnimation оборачивает Body + Footer (но не Header)
+
+```tsx
+{expandableContent
+  ? <ExpandAnimation expanded={open}>{renderContent()}</ExpandAnimation>
+  : <>{renderContent()}</>}
+```
+
+На desktop (не adaptive) или при `disableAdaptiveCollapsing=true` — без анимации, контент виден сразу.
+
+### `onClick` на wrapper'е Header'а, а не на Header'е
+
+```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
+
+```tsx
+<div className={clsx(styles.islandWidget, className, {
+    [styles.islandWidgetWithExtraFooter]: hasExtraFooter,
+})}>
+```
+
+Корневой Island меняет стиль (например, нижний радиус), когда снизу есть ExtraFooter. Это делает Wrapper'ом эффективным лишь для пары "IslandWidget + ExtraFooter". Без Wrapper'а контекст дефолтный (`hasExtraFooter=false`).
+
+---
+
+## Инварианты
+
+- **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 всегда виден.
+
+---
+
+## Accessibility
+
+- Клик по header'у на мобиле **не доступен с клавиатуры** (нет `tabIndex`/`role="button"`/keyboard handler). Known debt. Для критичных сценариев используйте `disableAdaptiveCollapsing` и навигацию через iOS/Android native.
+- Chevron-иконка — `aria-hidden="true"`, правильно.
+- Нет `aria-expanded`/`aria-controls` на wrapper'е — скринридер не анонсирует состояние. Known debt.
+- Остальное — прокидывается через `...htmlDivAttributes`.
+
+---
+
+## Дизайн-токены
+
+Нет собственных (все от `Island.TYPE_1`: `--triplex-next-Island-Type1_Background` / `_Shadow`).
+
+---
+
+## Связанные компоненты
+
+- `Island` — корневая карточка (hardcoded TYPE_1/MD внутри).
+- `IslandAccordion` — альтернатива для списка раскрывающихся элементов.
+- `ExpandAnimation` — используется для анимации сворачивания.
+- `MediaWidth.useMatchMedia` — детектирует адаптив.
+- `EScreenWidth` (`@sberbusiness/triplex-next/helpers/breakpoints`) — breakpoint SM_MAX.
+
+---
+
+## Stories
+
+`stories/IslandWidget/IslandWidget.stories.tsx`
+Примеры: `stories/IslandWidget/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/KeyDownListener.md

@@ -0,0 +1,157 @@
+---
+component: KeyDownListener
+category: Utilities
+figma-node: ""
+figma-file: ""
+related: [ComposedKeyDownListener, WindowResizeListener]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# KeyDownListener
+
+## Назначение
+
+Невизуальный компонент-слушатель `keydown` на `window`. При совпадении
+кода нажатой клавиши с `eventKeyCode` (одно значение или массив) вызывает
+`onMatch(event)`. Рендерит `children` как есть (или `null`) — не добавляет
+обёртку в DOM.
+
+Используй когда: нужно отреагировать на глобальное нажатие клавиш
+(Escape для закрытия модалки, Tab/ArrowKey для навигации в кастомных
+виджетах), но не привязываться к конкретному focus-target'у.
+
+Для нескольких параллельных слушателей используй `ComposedKeyDownListener` —
+принимает массив конфигов и композитит их в иерархию.
+
+---
+
+## Файловая структура
+
+```text
+src/components/KeyDownListener/
+├── KeyDownListener.tsx           # React.Component (class) с window-keydown
+├── ComposedKeyDownListener.tsx   # FC, сворачивает массив listener'ов в tree
+└── index.ts                      # Barrel: оба компонента
+```
+
+Нет styles, stories, tests.
+
+---
+
+## Варианты и props
+
+### KeyDownListener — `IKeyDownListenerProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `eventKeyCode` | `number \| number[]` | Да | Код клавиши (число — это `KeyboardEvent.keyCode`, не `key`). Один код или массив. |
+| `onMatch` | `(event: KeyboardEvent) => void` | Да | Вызывается при совпадении кода. |
+| `children` | `React.ReactNode` | Нет | Рендерятся "прозрачно" (компонент не оборачивает в DOM). |
+
+Тип кода: `keyCode = (typeof EVENT_KEY_CODES)[keyof typeof EVENT_KEY_CODES]`
+(числа из `@sberbusiness/triplex-next/utils/keyboard`): `ENTER=13`, `ESCAPE=27`,
+`TAB=9`, `ARROW_*=37-40`, и т.д.
+
+### ComposedKeyDownListener — `IKeyDownListenerManagerProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `keyDownListeners` | `IKeyDownListenerProps[]` | Да | Массив конфигов. Для каждого создаётся свой `KeyDownListener`. |
+| `children` | `React.ReactNode` | Нет | Обёрнуты всеми listener'ами в иерархию (последний в массиве — самый внешний). |
+
+---
+
+## Ключевые особенности реализации
+
+### `KeyDownListener` — class component
+
+```tsx
+export class KeyDownListener extends React.Component<IKeyDownListenerProps> {
+    public componentDidMount() { window.addEventListener("keydown", this.handleKeyDown); }
+    public componentWillUnmount() { window.removeEventListener("keydown", this.handleKeyDown); }
+    public render() { return this.props.children || null; }
+}
+```
+
+- **Сохранён как class**, хотя весь остальной код библиотеки — функциональные компоненты. Миграция на `useEffect` возможна, но class сохраняет идентичность listener'а через reference handler'а — аналог можно сделать через `useEffect` + стабильный handler (через ref на `onMatch`).
+- Не `forwardRef` — компонент не имеет своего DOM.
+
+### Использование `keyCode`, а не `key` / `code`
+
+```ts
+if (typeof eventKeyCode === "number") {
+    eventKeyCode === event.keyCode && onMatch(event);
+} else if (eventKeyCode.includes(event.keyCode)) {
+    onMatch(event);
+}
+```
+
+- `event.keyCode` — **deprecated** в современном вебе (замена: `event.key` или `event.code`). Компонент и набор `EVENT_KEY_CODES` сохранили legacy-подход.
+- Числовые константы (13, 27, 40, ...) должны использоваться через `EVENT_KEY_CODES.ENTER` / `.ESCAPE` и т.д., не литерально.
+- Для новых компонентов предпочитать `isKey(event.key, "ENTER")` из `utils/keyboard` — она поддерживает `key`-strings и legacy-fallback.
+
+### `onMatch` не кешируется в class state
+
+Каждый keydown вытаскивает `this.props.onMatch` актуальный — замыкание не устаревает. При миграции на hooks это поведение нужно воспроизвести через ref.
+
+### `ComposedKeyDownListener` — reduce-вариант через цикл
+
+```tsx
+let accumulatedElement = children as JSX.Element;
+for (let i = 0; i < keyDownListeners.length; i++) {
+    accumulatedElement = <KeyDownListener {...}>{accumulatedElement}</KeyDownListener>;
+}
+```
+
+- Последний listener в массиве → самый внешний wrapper в tree.
+- Порядок не влияет на результат (все listener'ы слушают `window` независимо), но Reactу важен для reconciliation — не менять порядок без нужды.
+- **Внимание:** ключи не проставляются. При рендере одного и того же конфига это ок, но при динамическом изменении массива React может ломать состояние child'ов — используй stable ordering.
+
+---
+
+## Инварианты
+
+- **`eventKeyCode` — `number | number[]`** (не `string`/`KeyboardEvent["key"]`). Публичный контракт. При смене на `key`-строки — breaking change.
+- **`onMatch(event: KeyboardEvent)`** — получает нативное событие, не синтетическое React-событие. Не менять тип на `React.KeyboardEvent`.
+- **Class component** — сохранить при рефакторинге; миграция на FC допустима, но должна воспроизвести `componentWillUnmount`-очистку и актуальный `onMatch`.
+- **`window.addEventListener`** — listener на окне, не на document. Не менять без согласования (влияет на порядок обработки событий с портальными элементами).
+- **`children` рендерятся без обёртки** — компонент "прозрачный" в DOM. Не добавлять `<div>`/`<Fragment>` без нужды.
+- **`ComposedKeyDownListener`** — простой композитор. Не усложнять (например, не добавлять `useMemo`/контексты) без реальной нужды.
+
+---
+
+## Accessibility
+
+- Компонент работает на уровне окна, перехватывает keydown до того, как фокусируемый элемент получит шанс обработать — при использовании **в составе интерактивных виджетов** учитывай, что нативный `onKeyDown` на inputе/кнопке сработает **после** глобального listener'а (из-за bubbling), но глобальный listener активен всегда, даже если фокус в другом месте.
+- Не подменяй focus management'ом. Для Escape в модалках предпочитай `focus trap` + `onKeyDown` на overlay'е.
+- Listener активен даже в скрытом state компонента-родителя, если сам KeyDownListener не размонтирован. Контролируй монтирование через условный рендеринг.
+
+---
+
+## Дизайн-токены
+
+Нет.
+
+---
+
+## Связанные компоненты
+
+- `ComposedKeyDownListener` — обёртка для нескольких listener'ов.
+- `WindowResizeListener` — аналогичный паттерн для resize.
+- `@sberbusiness/triplex-next/utils/keyboard` — `EVENT_KEY_CODES`, `EVENT_KEYS`, `isKey`.
+
+---
+
+## Stories
+
+Нет.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |