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

package/bundle/components/ComposedKeyDownListener.md

@@ -0,0 +1,323 @@
+---
+component: ComposedKeyDownListener
+category: KeyDownListener
+related: [KeyDownListener, TriggerClickOnKeyDownEvent, SelectExtendedField, SliderExtended]
+tokens: []
+stories: stories/ComposedKeyDownListener/ComposedKeyDownListener.stories.tsx
+version: "1.0"
+---
+
+# ComposedKeyDownListener
+
+## Назначение
+
+Сервисный headless-компонент, композитор `KeyDownListener`. Принимает массив
+конфигураций `keyDownListeners` и рендерит по одному `KeyDownListener` на элемент
+массива — соседями к `children`. Каждый слушатель подписывается на `keydown` на
+`window` независимо, поэтому компонент — это только способ описать несколько
+горячих клавиш одним объявлением вместо ручного вложения нескольких
+`KeyDownListener`.
+
+Собственной разметки не рендерит: `children` выводятся как есть, без обёртки;
+без `children` (и при любом наборе слушателей) DOM остаётся пустым — сами
+`KeyDownListener` рендерят `null`.
+
+Используй когда: у экрана или оверлея несколько глобальных горячих клавиш с
+разными обработчиками — `Enter` подтверждает, `Esc` отменяет, стрелки листают.
+
+Не используй когда:
+- Клавиша всего одна — достаточно `KeyDownListener` напрямую.
+- Клавиши разные, но обработчик один — у `KeyDownListener` `eventKeyCode`
+  принимает массив кодов; различить нажатую можно по `event.keyCode`.
+- Клавиша должна обрабатываться только внутри конкретного элемента — навесь
+  `onKeyDown` на сам элемент: слушатели здесь глобальные и сработают при вводе в
+  любое поле на странице.
+- Нужно кликнуть по конкретной кнопке по нажатию клавиши — есть готовый
+  `TriggerClickOnKeyDownEvent`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `keyDownListeners` | `IKeyDownListenerProps[]` | Конфигурация слушателей. Из каждого элемента используются только `eventKeyCode` и `onMatch`; поле `children` элемента игнорируется — содержимое задаётся `children` самого композитора |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Рендерится как есть, без обёртки. При пустом `keyDownListeners` компонент сводится к `children` |
+
+### Особенности поведения
+
+- Слушатели рендерятся **соседями** к `children`
+  (`<>{listeners}{children}</>`), а не оборачивают их. Поэтому `children` не
+  зависят от длины и порядка массива: набор горячих клавиш можно менять между
+  рендерами, содержимое при этом не перемонтируется — DOM-узлы, значения
+  инпутов, фокус и анимации сохраняются.
+- `onMatch` вызываются в порядке элементов `keyDownListeners`: слушатели
+  монтируются в порядке массива, а `window` вызывает обработчики в порядке
+  подписки. На нём завязан только порядок вызова — «перехватить» событие у
+  соседнего слушателя нельзя, все подписаны на `window` независимо.
+- Несколько элементов массива могут слушать одну и ту же клавишу — сработают
+  все.
+- Слушатели подписываются на `window` **до** `children`, потому что монтируются
+  раньше них. Если внутри `children` есть собственный глобальный
+  `keydown`-обработчик той же клавиши, `onMatch` сработает первым.
+- Компонент ничего не мемоизирует: массив можно собирать инлайн в рендере.
+  Каждый `KeyDownListener` читает свежие `eventKeyCode` и `onMatch` из props в
+  момент события, переподписки на новые ссылки не происходит.
+- `keyDownListeners` сопоставляются между рендерами по индексу (`key={index}`).
+  Для элементов конфигурации это безопасно: `KeyDownListener` не рендерит
+  разметку и не хранит внутренний state, поэтому переиспользование инстанса по
+  позиции наблюдаемого эффекта не даёт.
+
+---
+
+## Дизайн-токены
+
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
+
+---
+
+## Инварианты
+
+- **Имя prop `keyDownListeners`, `children` и интерфейс
+  `IComposedKeyDownListenerProps`** (экспортируется из barrel
+  `src/components/KeyDownListener/index.ts`) — публичное API, не менять.
+- **Элементы `keyDownListeners` типизированы `IKeyDownListenerProps`** —
+  переиспользование типа `KeyDownListener` осознанное; не заводить отдельный тип
+  ради «более узкого» `Pick`, это сузит публичный контракт.
+- **Плоский рендер слушателей** — не возвращаться к вложению
+  (`reduce` с оборачиванием `children`): вложенность делает глубину дерева
+  зависимой от длины массива и перемонтирует `children` при её изменении.
+- **Собственной разметки нет** — не добавлять обёртку (`div`, `span`) вокруг
+  `children`: потребители рассчитывают, что компонент прозрачен для layout,
+  в том числе внутри flex/grid-контейнеров.
+- **Без `forwardRef`** — осознанное исключение, как и у `KeyDownListener`:
+  компонент не рендерит собственный host-элемент, форвардить `ref` некуда.
+- Реализация остаётся React 17-совместимой (функциональный компонент без
+  React 18-only API): код синхронизируется в `release-0`.
+
+---
+
+## Accessibility
+
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева
+  и не рендерит фокусируемых элементов.
+- Горячие клавиши глобальные: перехватываются независимо от позиции фокуса и не
+  анонсируются screen reader'ом. Действия, повешенные на клавиши, должны быть
+  доступны и обычным путём (кнопкой) — шорткат не единственный способ выполнить
+  действие.
+- Компонент не проверяет, где находится фокус: `Enter` и `Esc` сработают и во
+  время ввода в поле. Если это нежелательно, фильтруй в `onMatch` по
+  `event.target`.
+
+---
+
+## Связанные компоненты
+
+- `KeyDownListener` (`src/components/KeyDownListener/KeyDownListener.tsx`) —
+  элементарный слушатель, из которого собирается композитор; там же описано
+  сравнение по устаревшему `event.keyCode` и константы `EVENT_KEY_CODES`.
+- `TriggerClickOnKeyDownEvent` (`src/components/Triggers/`) — по нажатию клавиши
+  вызывает `click` на элементе из `targetRef`.
+- `SelectExtendedField`, `SliderExtendedDot`, `SliderExtendedTrack` — потребители
+  `KeyDownListener` внутри библиотеки.
+
+---
+
+## Stories
+
+Основные истории: `stories/ComposedKeyDownListener/ComposedKeyDownListener.stories.tsx`
+Файлы примеров: `stories/ComposedKeyDownListener/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Набор клавиш выбирается чекбоксами: слушатели пересобираются, введённый текст сохраняется |
+| `Default` | `Default.tsx` | Две клавиши с разными обработчиками: `Enter` подтверждает, `Esc` отменяет |
+| `WithDynamicListeners` | `WithDynamicListeners.tsx` | Слушатель добавляется на лету — `children` не перемонтируются |
+| `Example` | `Example.tsx` | Панель подтверждения: горячие клавиши смонтированы вместе с панелью, те же действия доступны кнопками |
+
+Набор целиком исключён из скриншот-тестов (`testRunner: { skip: true }` в `meta`):
+собственной разметки компонент не рендерит, на скриншот попадала бы только
+обвязка примеров. Поведение слушателей покрыто unit-тестами.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-11 | Создан документ (TRI-112). Слушатели рендерятся соседями к `children` вместо вложения — смена длины `keyDownListeners` больше не перемонтирует содержимое (покрыто unit-тестом). Добавлен собственный набор stories по modern pattern; демонстрационная story `Example` перенесена из набора `KeyDownListener`. Публичный API не изменён. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/ComposedKeyDownListener/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ComposedKeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [result, setResult] = useState("Ожидание нажатия клавиши");
+
+    const keyDownListeners = [
+        { eventKeyCode: EVENT_KEY_CODES.ENTER, onMatch: () => setResult("Подтверждено по Enter") },
+        { eventKeyCode: EVENT_KEY_CODES.ESCAPE, onMatch: () => setResult("Отменено по Esc") },
+    ];
+
+    return (
+        <ComposedKeyDownListener keyDownListeners={keyDownListeners}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>Две горячие клавиши с разными обработчиками: Enter подтверждает, Esc отменяет.</div>
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    {result}
+                </div>
+            </div>
+        </ComposedKeyDownListener>
+    );
+};
+```
+
+### WithDynamicListeners
+
+`stories/ComposedKeyDownListener/examples/WithDynamicListeners.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { ComposedKeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const WithDynamicListeners = () => {
+    const [arrowsEnabled, setArrowsEnabled] = useState(false);
+    const [result, setResult] = useState("Ожидание нажатия клавиши");
+
+    const keyDownListeners = [
+        { eventKeyCode: EVENT_KEY_CODES.ESCAPE, onMatch: () => setResult("Отменено по Esc") },
+        ...(arrowsEnabled
+            ? [
+                  {
+                      eventKeyCode: [EVENT_KEY_CODES.ARROW_LEFT, EVENT_KEY_CODES.ARROW_RIGHT],
+                      onMatch: (event: KeyboardEvent) =>
+                          setResult(event.keyCode === EVENT_KEY_CODES.ARROW_LEFT ? "Стрелка влево" : "Стрелка вправо"),
+                  },
+              ]
+            : []),
+    ];
+
+    return (
+        <ComposedKeyDownListener keyDownListeners={keyDownListeners}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>Набор слушателей меняется на лету — содержимое при этом не перемонтируется.</div>
+                <input type="text" placeholder="Введите текст" style={{ padding: "8px", width: "100%" }} />
+                <label style={{ display: "flex", alignItems: "center", gap: "8px" }}>
+                    <input
+                        type="checkbox"
+                        checked={arrowsEnabled}
+                        onChange={(event) => setArrowsEnabled(event.target.checked)}
+                    />
+                    Добавить слушатель стрелок — введённый текст и фокус сохранятся
+                </label>
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    {result}
+                </div>
+            </div>
+        </ComposedKeyDownListener>
+    );
+};
+```
+
+### Example
+
+`stories/ComposedKeyDownListener/examples/Example.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import {
+    Button,
+    ComposedKeyDownListener,
+    EButtonTheme,
+    EComponentSize,
+    EVENT_KEY_CODES,
+} from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [opened, setOpened] = useState(true);
+    const [status, setStatus] = useState("Черновик не сохранён");
+    const panelRef = useRef<HTMLDivElement>(null);
+
+    const handleSave = () => {
+        setStatus("Черновик сохранён");
+        setOpened(false);
+    };
+
+    const handleCancel = () => {
+        setStatus("Сохранение отменено");
+        setOpened(false);
+    };
+
+    // Слушатели глобальные, поэтому Enter на сфокусированной кнопке панели дошёл бы
+    // и до onMatch, и до её onClick. Отфильтровываем такие события по event.target —
+    // действие кнопки должно выигрывать у горячей клавиши.
+    const handleSaveOnEnter = (event: KeyboardEvent) => {
+        if (event.target instanceof HTMLButtonElement && panelRef.current?.contains(event.target)) {
+            return;
+        }
+
+        handleSave();
+    };
+
+    // Слушатели монтируются только вместе с панелью, поэтому горячие клавиши
+    // работают лишь пока она открыта.
+    const keyDownListeners = [
+        { eventKeyCode: EVENT_KEY_CODES.ENTER, onMatch: handleSaveOnEnter },
+        { eventKeyCode: EVENT_KEY_CODES.ESCAPE, onMatch: handleCancel },
+    ];
+
+    if (!opened) {
+        return (
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>{status}</div>
+                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={() => setOpened(true)}>
+                    Открыть панель снова
+                </Button>
+            </div>
+        );
+    }
+
+    return (
+        <ComposedKeyDownListener keyDownListeners={keyDownListeners}>
+            <div
+                ref={panelRef}
+                style={{
+                    display: "flex",
+                    flexDirection: "column",
+                    gap: "16px",
+                    maxWidth: "400px",
+                    border: "1px solid rgb(125, 131, 138)",
+                    borderRadius: "8px",
+                    padding: "16px",
+                }}
+            >
+                <div>Сохранить черновик? Enter — сохранить, Esc — отменить.</div>
+                <div style={{ display: "flex", gap: "8px" }}>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleSave}>
+                        Сохранить
+                    </Button>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleCancel}>
+                        Отменить
+                    </Button>
+                </div>
+            </div>
+        </ComposedKeyDownListener>
+    );
+};
+```
+

package/bundle/components/FooterPage.md

@@ -39,7 +39,7 @@ version: "1.0"
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `sticky` | `boolean` | `false` | Футер прилипает к нижней границе при скролле. **Только для `type=FIRST`** (внутри `LightBox`); для `type=SECOND` типизирован как `never`. |
+| `sticky` | `boolean` | `false` | Футер прилипает к нижней границе при скролле, если ширина viewport от 992px, а высота больше 800px. **Только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
 | `size` | `EComponentSize` | — | Размер острова (Island). **Доступен только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
 
 ### Ограничения по типам
@@ -111,6 +111,7 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-08-06 | Sticky-позиционирование доступно вне `LightBox` при ширине viewport от 992px и отключено при высоте viewport не больше 800px. |
 | 2026-06-19 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
 
 ---