@sberbusiness/triplex-next-mcp-server 0.36.0-beta0 → 1.41.0-beta

package/bundle/components/KeyDownListener.md

@@ -1,11 +1,9 @@
 ---
 component: KeyDownListener
-category: Utilities
-figma-node: ""
-figma-file: ""
-related: [ComposedKeyDownListener, WindowResizeListener]
+category: KeyDownListener
+related: [ComposedKeyDownListener, TriggerClickOnKeyDownEvent, SelectExtendedField, SliderExtended]
 tokens: []
-stories: ""
+stories: stories/KeyDownListener/KeyDownListener.stories.tsx
 version: "1.0"
 ---
 
@@ -13,145 +11,260 @@ version: "1.0"
 
 ## Назначение
 
-Невизуальный компонент-слушатель `keydown` на `window`. При совпадении
-кода нажатой клавиши с `eventKeyCode` (одно значение или массив) вызывает
-`onMatch(event)`. Рендерит `children` как есть (или `null`) — не добавляет
-обёртку в DOM.
+Сервисный headless-компонент. Пока смонтирован, слушает `keydown` на `window` и
+вызывает `onMatch`, если числовой код нажатой клавиши (`event.keyCode`) совпал с
+`eventKeyCode`. Собственной разметки не рендерит: `children` выводятся как есть,
+без обёртки; без `children` не рендерит ничего.
 
-Используй когда: нужно отреагировать на глобальное нажатие клавиш
-(Escape для закрытия модалки, Tab/ArrowKey для навигации в кастомных
-виджетах), но не привязываться к конкретному focus-target'у.
+Используй когда: нужна глобальная (документная) горячая клавиша, работающая
+независимо от того, где находится фокус — закрытие оверлея по `Esc`, стрелки для
+управления слайдером/ползунком, подтверждение по `Enter`.
 
-Для нескольких параллельных слушателей используй `ComposedKeyDownListener` —
-принимает массив конфигов и композитит их в иерархию.
-
----
-
-## Файловая структура
-
-```text
-src/components/KeyDownListener/
-├── KeyDownListener.tsx           # React.Component (class) с window-keydown
-├── ComposedKeyDownListener.tsx   # FC, сворачивает массив listener'ов в tree
-└── index.ts                      # Barrel: оба компонента
-```
-
-Нет styles, stories, tests.
+Не используй когда:
+- Клавиша должна обрабатываться только внутри конкретного элемента — навесь
+  `onKeyDown` на сам элемент, иначе обработчик сработает при вводе в другое поле
+  на странице.
+- Нужно кликнуть по конкретной кнопке по нажатию клавиши — есть готовый
+  `TriggerClickOnKeyDownEvent`.
+- Нужно несколько разных клавиш с разными обработчиками — используй
+  `ComposedKeyDownListener` (см. «Связанные компоненты»).
 
 ---
 
 ## Варианты и props
 
-### KeyDownListener — `IKeyDownListenerProps`
+### Обязательные props
 
-| 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`, и т.д.
+| Prop | Тип | Описание |
+|---|---|---|
+| `eventKeyCode` | `number \| number[]` | Код клавиши из `EVENT_KEY_CODES` или массив кодов. Массив — «любая из перечисленных клавиш»; различить нажатую можно по `event.keyCode` внутри `onMatch` |
+| `onMatch` | `(event: KeyboardEvent) => void` | Вызывается при совпадении. Получает нативный `KeyboardEvent` (не React SyntheticEvent) |
 
-### ComposedKeyDownListener — `IKeyDownListenerManagerProps`
+### Опциональные props
 
-| Prop | Тип | Обязателен | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `keyDownListeners` | `IKeyDownListenerProps[]` | Да | Массив конфигов. Для каждого создаётся свой `KeyDownListener`. |
-| `children` | `React.ReactNode` | Нет | Обёрнуты всеми listener'ами в иерархию (последний в массиве — самый внешний). |
+| `children` | `React.ReactNode` | — | Рендерится как есть. Компонент не оборачивает содержимое и никак на него не влияет — вложение нужно только для читаемости кода |
+
+### Особенности поведения
+
+- Слушатель навешивается на `window` в `componentDidMount` и снимается в
+  `componentWillUnmount`. Компонент не вызывает `preventDefault` и не
+  останавливает всплытие — это ответственность `onMatch`.
+- Сравнение идёт по устаревшему `event.keyCode`, а не по `event.key`. Коды
+  берутся из `EVENT_KEY_CODES` (`@sberbusiness/triplex-next`); не хардкодь числа.
+- `onMatch` и `eventKeyCode` читаются из `this.props` в момент события, поэтому
+  свежие значения после rerender применяются без переподписки.
+- Несколько смонтированных `KeyDownListener` на одну клавишу срабатывают все —
+  порядок соответствует порядку монтирования.
+- Компонент не проверяет, где находится фокус: `Esc` сработает и во время ввода
+  в поле. Если это нежелательно, фильтруй в `onMatch` по `event.target`.
 
 ---
 
-## Ключевые особенности реализации
-
-### `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; }
-}
-```
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
 
-- **Сохранён как 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);
-}
-```
+- **`KeyDownListener` — class-компонент**, и это часть публичного контракта:
+  `ref` указывает на инстанс класса, метод `handleKeyDown` публичный. Не
+  переписывать на функциональный компонент.
+- **Без `forwardRef` — осознанное исключение** из общего правила библиотеки:
+  компонент не рендерит собственный host-элемент, форвардить ref некуда.
+- **Имена props `children`, `eventKeyCode`, `onMatch`** и интерфейс
+  `IKeyDownListenerProps` (экспортируется из barrel) — публичное API, не менять.
+  `IKeyDownListenerProps` переиспользуется в `TriggerClickOnKeyDownEvent`
+  (`Pick<IKeyDownListenerProps, "eventKeyCode">`) и в props
+  `ComposedKeyDownListener`.
+- **Сравнение по `event.keyCode`** — не мигрировать на `event.key` без отдельной
+  задачи: у `EVENT_KEYS.SPACE` значения `["Spacebar", "Space"]` не совпадают с
+  современным `event.key === " "`, и миграция изменит наблюдаемое поведение у
+  потребителей.
+- **`render` возвращает `this.props.children || null`** — falsy-`children`
+  (`0`, `""`) осознанно дают `null`. Не заменять на `??`.
+- Реализация остаётся React 17-совместимой (класс, без хуков и React 18-only
+  API): код синхронизируется в `release-0`.
 
-- `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
+## Accessibility
 
-Каждый keydown вытаскивает `this.props.onMatch` актуальный — замыкание не устаревает. При миграции на hooks это поведение нужно воспроизвести через ref.
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева
+  и не рендерит фокусируемых элементов.
+- Горячая клавиша глобальная: она перехватывается независимо от позиции фокуса и
+  не анонсируется screen reader'ом. Если клавиша дублирует видимое действие,
+  оставь пользователю и обычный путь (кнопку) — клавиатурный шорткат не должен
+  быть единственным способом выполнить действие.
+- `Esc` для закрытия оверлеев — ожидаемое поведение; возврат фокуса на триггер
+  после закрытия компонент не делает, это ответственность потребителя.
 
-### `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.
+### `ComposedKeyDownListener` (`src/components/KeyDownListener/ComposedKeyDownListener.tsx`)
+
+Композитор: оборачивает `children` в `KeyDownListener` по одному на каждый
+элемент `keyDownListeners`. Экспортируется из того же barrel вместе со своим
+интерфейсом props `IComposedKeyDownListenerProps` — публичное API, не менять.
+
+Собственного AI.md пока не имеет — вся его логика описана здесь. По правилу
+`docs/ai/CONTEXT.md` § «Когда создавать `{ComponentName}-ai.md`» он его
+заслуживает (оба условия выполнены: barrel-экспорт + собственный prop
+`keyDownListeners`), но по scope задачи TRI-48 соседние экспортируемые
+компоненты выносятся в отдельные задачи. Компонент добавлен отдельной строкой в
+`docs/ai/ROADMAP.md`, документ будет заведён своей задачей. Следствие, о котором
+нужно знать до тех пор: `scripts/generateMcpData.ts` собирает записи по файлам
+`src/components/*/*-ai.md`, поэтому отдельной записи в `mcp-data.json` у
+`ComposedKeyDownListener` нет — агент найдёт его только через этот документ.
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `keyDownListeners` | `IKeyDownListenerProps[]` | Конфигурация слушателей. Используются только `eventKeyCode` и `onMatch`, поле `children` каждого элемента игнорируется |
+| `children` | `React.ReactNode` | Содержимое. Рендерится как есть; при пустом `keyDownListeners` — просто `children` |
+
+Первый элемент массива оказывается самым внутренним слушателем. На порядок
+срабатывания это влияет слабо — все слушатели подписаны на `window` независимо
+друг от друга, а порядок вызова совпадает с порядком элементов массива.
+
+**Ограничение: длина `keyDownListeners` должна быть стабильной между рендерами.**
+Глубина вложенности равна длине массива, поэтому при её изменении на позиции,
+где раньше были `children`, React монтирует новый `KeyDownListener`, а сами
+`children` уезжают на уровень ниже и перемонтируются: DOM-узлы пересоздаются,
+введённые значения инпутов, фокус и текущие анимации теряются. Если набор
+слушателей динамический — держи массив постоянной длины (например, с
+`onMatch`-заглушками) или используй `KeyDownListener` напрямую.
+
+### Потребители внутри библиотеки
+
+- `TriggerClickOnKeyDownEvent` (`src/components/Triggers/`) — по нажатию клавиши
+  вызывает `click` на элементе из `targetRef`.
+- `SelectExtendedField` — закрывает выпадающий список по `Esc`.
+- `SliderExtendedDot`, `SliderExtendedTrack` — стрелки для перемещения ползунка,
+  слушатели монтируются только когда элемент в фокусе.
 
 ---
 
-## Инварианты
+## Stories
+
+Основные истории: `stories/KeyDownListener/KeyDownListener.stories.tsx`
+Файлы примеров: `stories/KeyDownListener/examples/`
 
-- **`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`/контексты) без реальной нужды.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный выбор `eventKeyCode` и счётчик срабатываний `onMatch` |
+| `Default` | `Default.tsx` | Слушатель одной клавиши: панель скрывается по `Esc` |
+| `WithMultipleKeys` | `WithMultipleKeys.tsx` | Массив кодов в `eventKeyCode`; нажатая клавиша различается по `event.keyCode` |
+| `Example` | `Example.tsx` | `ComposedKeyDownListener`: `Enter` подтверждает, `Esc` отменяет |
+| `VisualTests` | — | Состояние после срабатывания слушателя: `play` диспатчит на `window` `keydown` с `keyCode` клавиши `Esc` |
 
 ---
 
-## Accessibility
+## История изменений
 
-- Компонент работает на уровне окна, перехватывает keydown до того, как фокусируемый элемент получит шанс обработать — при использовании **в составе интерактивных виджетов** учитывай, что нативный `onKeyDown` на inputе/кнопке сработает **после** глобального listener'а (из-за bubbling), но глобальный listener активен всегда, даже если фокус в другом месте.
-- Не подменяй focus management'ом. Для Escape в модалках предпочитай `focus trap` + `onKeyDown` на overlay'е.
-- Listener активен даже в скрытом state компонента-родителя, если сам KeyDownListener не размонтирован. Контролируй монтирование через условный рендеринг.
+| Дата | Изменение |
+|---|---|
+| 2026-08-04 | По ревью PR #502: интерфейс props `IComposedKeyDownListenerProps` стал экспортируемым — публичная поверхность пакета расширена аддитивно. `ComposedKeyDownListener` добавлен отдельной строкой в `docs/ai/ROADMAP.md`, собственный AI.md вынесен в отдельную задачу. |
+| 2026-08-04 | Создан документ. AI-рефакторинг (TRI-48): JSDoc на props `IKeyDownListenerProps` и `ComposedKeyDownListener`, ветвление в `handleKeyDown` сведено к одной проверке (снят `eslint-disable`), в `ComposedKeyDownListener` убран `as JSX.Element` и добавлен `displayName`, unit-тесты (16 кейсов на оба компонента), stories по modern pattern. Публичный API не менялся; компонент остаётся class-компонентом, `forwardRef` осознанно отсутствует. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-Нет.
+### Default
 
----
+`stories/KeyDownListener/examples/Default.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { KeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [visible, setVisible] = useState(true);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <KeyDownListener eventKeyCode={EVENT_KEY_CODES.ESCAPE} onMatch={() => setVisible(false)} />
+            <div>Нажмите Esc, чтобы скрыть панель.</div>
+            {visible && (
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    Панель скрывается по нажатию Esc в любом месте страницы.
+                </div>
+            )}
+        </div>
+    );
+};
+```
 
-- `ComposedKeyDownListener` — обёртка для нескольких listener'ов.
-- `WindowResizeListener` — аналогичный паттерн для resize.
-- `@sberbusiness/triplex-next/utils/keyboard` — `EVENT_KEY_CODES`, `EVENT_KEYS`, `isKey`.
+### WithMultipleKeys
 
----
+`stories/KeyDownListener/examples/WithMultipleKeys.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { KeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const WithMultipleKeys = () => {
+    const [value, setValue] = useState(0);
+
+    const handleMatch = (event: KeyboardEvent) => {
+        setValue((prevValue) => (event.keyCode === EVENT_KEY_CODES.ARROW_LEFT ? prevValue - 1 : prevValue + 1));
+    };
+
+    return (
+        <KeyDownListener eventKeyCode={[EVENT_KEY_CODES.ARROW_LEFT, EVENT_KEY_CODES.ARROW_RIGHT]} onMatch={handleMatch}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>Один слушатель реагирует на несколько клавиш: стрелка влево и стрелка вправо.</div>
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    Значение: {value}
+                </div>
+            </div>
+        </KeyDownListener>
+    );
+};
+```
 
-Нет.
+### Example
 
----
+`stories/KeyDownListener/examples/Example.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { ComposedKeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [result, setResult] = useState<string | null>(null);
+
+    const keyDownListeners = [
+        { eventKeyCode: EVENT_KEY_CODES.ENTER, onMatch: () => setResult("Подтверждено по Enter") },
+        { eventKeyCode: EVENT_KEY_CODES.ESCAPE, onMatch: () => setResult("Отменено по Esc") },
+    ];
+
+    if (result !== null) {
+        return (
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>{result}</div>
+                <button type="button" onClick={() => setResult(null)}>
+                    Показать панель снова
+                </button>
+            </div>
+        );
+    }
+
+    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" }}>
+                    Ожидание нажатия клавиши.
+                </div>
+            </div>
+        </ComposedKeyDownListener>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |