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

package/bundle/components/TriggerClickOnKeyDownEvent.md

@@ -0,0 +1,277 @@
+---
+component: TriggerClickOnKeyDownEvent
+category: Triggers
+related: [KeyDownListener, ComposedKeyDownListener, LightBox]
+tokens: []
+stories: stories/TriggerClickOnKeyDownEvent/TriggerClickOnKeyDownEvent.stories.tsx
+version: "1.0"
+---
+
+# TriggerClickOnKeyDownEvent
+
+## Назначение
+
+Сервисный headless-компонент. Пока смонтирован, слушает `keydown` на `window`
+(через `KeyDownListener`) и при совпадении кода нажатой клавиши с `eventKeyCode`
+вызывает нативный `click()` на кнопке из `targetRef`. Собственной разметки не
+рендерит: `children` выводятся как есть.
+
+Используй когда: действие уже реализовано кнопкой, и его нужно продублировать
+глобальной горячей клавишей — закрытие оверлея по `Esc`, листание галереи
+стрелками. Клик по настоящей кнопке даёт потребителю один обработчик вместо двух
+и сохраняет поведение кнопки (`disabled`, `onClick`, аналитика).
+
+Не используй когда:
+- Нужно выполнить произвольный обработчик, а не клик по кнопке — бери
+  `KeyDownListener` напрямую.
+- Нужно несколько разных клавиш с разными действиями — `ComposedKeyDownListener`.
+- Клавиша должна работать только внутри конкретного элемента — навесь `onKeyDown`
+  на сам элемент: слушатель здесь глобальный и сработает при вводе в любое поле
+  на странице.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `eventKeyCode` | `number \| number[]` | Код клавиши из `EVENT_KEY_CODES` или массив кодов. Тип переиспользуется из `IKeyDownListenerProps` через `Pick` |
+| `targetRef` | `React.RefObject<HTMLButtonElement>` | Ссылка на кнопку, по которой выполняется клик. Кнопка не обязана находиться внутри `children` |
+| `children` | `React.ReactElement` | Рендерится как есть. Обязателен по типу (в отличие от `KeyDownListener`), обёртки над ним компонент не создаёт |
+
+### Особенности поведения
+
+- **Клик выполняется только по видимой кнопке.** Перед `click()` проверяется
+  `buttonEl.offsetParent !== null` — у элемента, скрытого через `display: none`
+  (своим стилем или стилем предка), `offsetParent` равен `null`. На этом
+  построены `LightBoxClose` и `LightBoxArrow`: десктопная и мобильная копии
+  кнопки переключаются через `display: none`, оба триггера смонтированы, но
+  срабатывает только видимый.
+- **Проверка не покрывает другие способы скрытия.** `visibility: hidden`,
+  `opacity: 0`, нулевой размер и вынос за пределы вьюпорта дают ненулевой
+  `offsetParent`, и клик пройдёт. Отдельный случай — **собственный**
+  `position: fixed` у самой кнопки: у такого элемента `offsetParent` тоже
+  `null`, поэтому клавишей он не кликается. `fixed` на предке на проверку не
+  влияет — тогда `offsetParent` кнопки равен ближайшему позиционированному
+  предку, то есть самому `fixed`-контейнеру. Поэтому `ModalWindowClose` и
+  `LightBoxClose`, живущие внутри `fixed`-оверлеев, по Esc работают.
+- **Пустой `targetRef` безопасен.** Если `targetRef.current === null` (кнопка не
+  смонтирована), обработчик молча ничего не делает.
+- **Клик синтезируется через нативный `HTMLElement.click()`**, а не через
+  `dispatchEvent` с кастомным событием: `onClick` кнопки получает обычное
+  `click`-событие с `event.detail === 0`. `disabled`-кнопка такой клик нативно
+  игнорирует.
+- Триггеры **вкладываются друг в друга**, когда одна клавиша должна обслуживать
+  несколько кнопок (`LightBoxClose`, `LightBoxArrow`): каждый уровень добавляет
+  свой `KeyDownListener` и не влияет на `children`.
+- Компонент не вызывает `preventDefault` и не останавливает всплытие — нажатие
+  клавиши дойдёт и до других слушателей.
+
+---
+
+## Дизайн-токены
+
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
+
+---
+
+## Инварианты
+
+- **`forwardRef` осознанно отсутствует** — то же исключение, что у
+  `KeyDownListener`: компонент не рендерит собственный host-элемент, форвардить
+  `ref` некуда. Добавление `forwardRef` изменило бы публичный тип компонента с
+  `React.FC` на `React.ForwardRefExoticComponent` — не делать.
+- **`ITriggerClickOnKeyDownEventProps` экспортируется** — из файла и через
+  `export *` в barrel, как у остальных компонентов библиотеки. Интерфейс —
+  часть публичного API: имена и типы полей не менять.
+- **Имена props `children`, `eventKeyCode`, `targetRef`** и barrel-экспорт
+  `TriggerClickOnKeyDownEvent` из `src/components/Triggers/index.ts` — публичное
+  API, не менять.
+- **Тип `targetRef` — `RefObject<HTMLButtonElement>`**, а не `Ref`: компоненту
+  нужен доступ к `.current`, callback-ref сюда не подходит.
+- **Проверка `offsetParent !== null`** — часть контракта, а не оптимизация. Её
+  снятие сломает `LightBoxClose`/`LightBoxArrow`: клавиша начнёт кликать скрытые
+  копии кнопок. Тест `does not click the target button when it is hidden`
+  фиксирует это поведение.
+- Реализация остаётся React 17-совместимой (без хуков-новинок React 18): код
+  синхронизируется в ветку `release-0`.
+
+---
+
+## Accessibility
+
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева.
+- Горячая клавиша глобальная и не анонсируется screen reader'ом, но действие
+  всегда доступно и обычным путём — через саму кнопку. Это и есть причина
+  кликать по кнопке, а не вызывать обработчик напрямую.
+- `Esc` для закрытия оверлеев — ожидаемое поведение. Возврат фокуса на триггер
+  после закрытия компонент не делает: это ответственность потребителя
+  (`ModalWindow`, `LightBox`).
+- Если кнопка иконочная, доступное имя (`title` / `aria-label`) передаёт
+  потребитель — библиотека мультиязычная и текст внутри не хардкодит.
+
+---
+
+## Связанные компоненты
+
+- `KeyDownListener` (`src/components/KeyDownListener/`) — слушатель клавиш, на
+  котором построен триггер. Нужен, когда по клавише выполняется произвольный
+  обработчик, а не клик по кнопке.
+- `ComposedKeyDownListener` — несколько клавиш с разными обработчиками; альтернатива,
+  когда действий по клавишам больше одного и они не сводятся к клику по кнопке.
+- `LightBox` — потребитель, который опирается на проверку видимости: `LightBoxClose`
+  и `LightBoxArrow` держат смонтированными по два триггера на одну клавишу
+  (десктопная и мобильная копии кнопки) и рассчитывают, что сработает только
+  видимая.
+
+### Остальные потребители внутри библиотеки
+
+- `ModalWindowClose` — закрытие модального окна по `Esc`.
+- `Confirm.Close` — закрытие подтверждения по `Esc` при `clickByEsc`.
+- `LightBoxSideOverlayCloseDesktop` — закрытие бокового оверлея лайтбокса по `Esc`.
+
+---
+
+## Stories
+
+Основные истории: `stories/TriggerClickOnKeyDownEvent/TriggerClickOnKeyDownEvent.stories.tsx`
+Файлы примеров: `stories/TriggerClickOnKeyDownEvent/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный выбор `eventKeyCode` и переключатель видимости кнопки |
+| `Default` | `Default.tsx` | Кнопка закрытия панели кликается по `Esc` |
+| `WithMultipleKeys` | `WithMultipleKeys.tsx` | Массив кодов в `eventKeyCode`: кнопка кликается по `Enter` и по стрелке вправо |
+| `WithHiddenTarget` | `WithHiddenTarget.tsx` | Вложенные триггеры на одну клавишу; скрытая через `display: none` кнопка пропускается |
+
+Набор целиком исключён из скриншот-тестов (`testRunner: { skip: true }` в `meta`):
+собственной разметки компонент не рендерит, на скриншот попадала бы только
+обвязка примеров. Поведение покрыто unit-тестами
+(`src/components/Triggers/__tests__/TriggerClickOnKeyDownEvent.test.tsx`).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-09-17 | Создан документ. AI-рефакторинг (TRI-101): JSDoc на props и на обработчик клавиши, ветвление в обработчике сведено к одной проверке, импорт React поднят в начало файла; unit-тесты (9 кейсов), stories по modern pattern. `forwardRef` осознанно отсутствует. По итогам ревью PR #628 `ITriggerClickOnKeyDownEventProps` стал экспортируемым — аддитивное расширение публичного API, приведение к общей конвенции репозитория. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/TriggerClickOnKeyDownEvent/examples/Default.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { Button, EButtonTheme, EVENT_KEY_CODES, TriggerClickOnKeyDownEvent } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const closeButtonRef = useRef<HTMLButtonElement>(null);
+    const [visible, setVisible] = useState(true);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <div>Нажмите Esc или кнопку «Закрыть» — панель скроется.</div>
+            {visible && (
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    <TriggerClickOnKeyDownEvent eventKeyCode={EVENT_KEY_CODES.ESCAPE} targetRef={closeButtonRef}>
+                        <Button ref={closeButtonRef} onClick={() => setVisible(false)} theme={EButtonTheme.SECONDARY}>
+                            Закрыть
+                        </Button>
+                    </TriggerClickOnKeyDownEvent>
+                </div>
+            )}
+        </div>
+    );
+};
+```
+
+### WithMultipleKeys
+
+`stories/TriggerClickOnKeyDownEvent/examples/WithMultipleKeys.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { Button, EButtonTheme, EVENT_KEY_CODES, TriggerClickOnKeyDownEvent } from "@sberbusiness/triplex-next";
+
+export const WithMultipleKeys = () => {
+    const nextButtonRef = useRef<HTMLButtonElement>(null);
+    const [step, setStep] = useState(1);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <div>Кнопка кликается и по Enter, и по стрелке вправо — в eventKeyCode передан массив кодов.</div>
+            <TriggerClickOnKeyDownEvent
+                eventKeyCode={[EVENT_KEY_CODES.ENTER, EVENT_KEY_CODES.ARROW_RIGHT]}
+                targetRef={nextButtonRef}
+            >
+                <Button
+                    ref={nextButtonRef}
+                    onClick={() => setStep((prevStep) => prevStep + 1)}
+                    theme={EButtonTheme.GENERAL}
+                >
+                    Дальше
+                </Button>
+            </TriggerClickOnKeyDownEvent>
+            <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                Шаг: {step}
+            </div>
+        </div>
+    );
+};
+```
+
+### WithHiddenTarget
+
+`stories/TriggerClickOnKeyDownEvent/examples/WithHiddenTarget.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { Button, EButtonTheme, EVENT_KEY_CODES, TriggerClickOnKeyDownEvent } from "@sberbusiness/triplex-next";
+
+export const WithHiddenTarget = () => {
+    const visibleButtonRef = useRef<HTMLButtonElement>(null);
+    const hiddenButtonRef = useRef<HTMLButtonElement>(null);
+    const [lastClicked, setLastClicked] = useState("—");
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <div>
+                Два триггера на одну клавишу: по Esc кликается только видимая кнопка, скрытая через display: none
+                пропускается.
+            </div>
+            <TriggerClickOnKeyDownEvent eventKeyCode={EVENT_KEY_CODES.ESCAPE} targetRef={visibleButtonRef}>
+                <TriggerClickOnKeyDownEvent eventKeyCode={EVENT_KEY_CODES.ESCAPE} targetRef={hiddenButtonRef}>
+                    <>
+                        <Button
+                            ref={visibleButtonRef}
+                            onClick={() => setLastClicked("видимая кнопка")}
+                            theme={EButtonTheme.SECONDARY}
+                        >
+                            Видимая кнопка
+                        </Button>
+                        <Button
+                            ref={hiddenButtonRef}
+                            onClick={() => setLastClicked("скрытая кнопка")}
+                            theme={EButtonTheme.SECONDARY}
+                            style={{ display: "none" }}
+                        >
+                            Скрытая кнопка
+                        </Button>
+                    </>
+                </TriggerClickOnKeyDownEvent>
+            </TriggerClickOnKeyDownEvent>
+            <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                Последний клик: {lastClicked}
+            </div>
+        </div>
+    );
+};
+```
+

package/bundle/components/UploadZone.md

@@ -0,0 +1,318 @@
+---
+component: UploadZone
+category: UploadZone
+related: []
+tokens:
+  - UploadZone.Background_Default
+  - UploadZone.Background_Hover
+  - UploadZone.BorderColor_Default
+  - UploadZone.DragArea_Background
+  - UploadZone.DragArea_BorderColor
+stories: stories/UploadZone/UploadZone.stories.tsx
+version: "1.0"
+---
+
+# UploadZone
+
+## Назначение
+
+Зона загрузки файлов: кликабельная область с пунктирной рамкой, открывающая
+системный диалог выбора файлов, и опциональная дроп-зона, которая раскрывается
+поверх заданного контейнера, пока пользователь перетаскивает файлы.
+
+Собственного содержимого компонент не рисует — разметка передаётся
+render-функцией в `children`, а результат выбора приходит одним обработчиком
+`onChange` и для диалога, и для drag-and-drop.
+
+Используй когда: нужен блок «перетащите файл или выберите на компьютере»,
+в том числе с подсветкой всей области формы/карточки при перетаскивании.
+Не используй когда: нужен готовый список загруженных файлов со статусами —
+`UploadZone` отвечает только за приём файлов, таблицу/список строит потребитель
+(см. story `Example: production`); нужна кнопка загрузки без зоны
+перетаскивания — достаточно обычного `<input type="file">` рядом с `Button`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `(props: IUploadZoneChildrenProvideProps) => React.ReactNode` | Render-функция содержимого зоны. Получает `openUploadDialog` |
+| `onChange` | `UploadZoneOnChangeType` | Единый обработчик выбора файлов: `(files: FileList \| null, e: React.SyntheticEvent) => void`. Вызывается и при выборе через диалог, и при drop |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `dropZoneContainer` | `HTMLElement \| null` | `undefined` | Контейнер, на площади которого перехватывается перетаскивание. Без него drag-and-drop не работает вовсе |
+| `renderContainerContent` | `() => JSX.Element` | `undefined` | Контент внутри дроп-зоны (иконка + подпись «Положите файлы сюда») |
+
+Остальные props — `Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "children">`.
+
+### Куда попадают `className`, `ref` и `...rest`
+
+Это главная неочевидность компонента:
+
+- **`ref`** указывает на корневой `<div class="uploadZone">` — обёртку,
+  которая задаёт фон и `position: relative`.
+- **`className` и все остальные HTML-атрибуты** уходят **не** на корневой
+  элемент, а на абсолютно позиционированный слой-перехватчик кликов
+  (`uploadZoneDragArea`) внутри него. Те же `className` и `...rest`
+  дублируются на слой дроп-зоны (`uploadZoneContainerDragArea`), когда он
+  смонтирован.
+- **`onDrop` и `onDragOver`** вынимаются из `...rest` отдельно и вешаются
+  только на дроп-зону. `onDragOver` вызывается после `preventDefault()`,
+  `onDrop` — до `onChange`.
+- `onClick` из `...rest` раскладывается **после** внутреннего обработчика, поэтому
+  переданный `onClick` полностью заменяет открытие диалога по клику на зону.
+
+### `UploadZone.Input` — поле выбора файлов
+
+Составная часть: `UploadZone.Input` (он же экспортируемый `UploadZoneInput`).
+
+- Рендерится внутри `children` и обязателен, если нужен диалог выбора файлов:
+  `openUploadDialog()` вызывает `click()` именно на нём. Без `UploadZone.Input`
+  и клик по зоне, и `openUploadDialog()` ничего не делают.
+- Поле скрыто (`display: none`) и потому не фокусируется — доступную точку
+  входа даёт потребитель (см. Accessibility).
+- Свой `onChange` полем не поддерживается (`Omit<..., "onChange">`): изменение
+  всегда уходит в `onChange` родительского `UploadZone` через контекст.
+  Остальные атрибуты (`multiple`, `accept`, `disabled`, `data-*`) проходят как есть.
+- При клике поле сбрасывает `value`, иначе повторный выбор того же файла не
+  вызовет `change`.
+- `ref` пробрасывается на `<input>`; параллельно ссылка кладётся во внутренний
+  контекст — переданный потребителем ref её не отменяет.
+
+### Как работает дроп-зона
+
+- Слушатели `dragenter` / `dragleave` вешаются на `dropZoneContainer`.
+  Счётчик вложенных `dragenter` (события всплывают от дочерних элементов)
+  не даёт зоне мигать при движении курсора над содержимым.
+- Пока идёт перетаскивание, в `dropZoneContainer` добавляется отдельный
+  `<div>` с собственным React-root (`createRoot`), в нём рендерится дроп-зона
+  на всю площадь контейнера. После `drop` или ухода курсора узел удаляется,
+  а root размонтируется на следующем микротаске.
+- Контент дроп-зоны формируется **один раз** в момент появления. Изменение
+  `renderContainerContent` или `className` во время перетаскивания на уже
+  открытую зону не влияет.
+- Контейнеру нужен `position: relative` (и `display: flow-root`, если зона
+  должна накрывать блок целиком) — слой позиционируется абсолютно по всем
+  четырём сторонам.
+
+### Мобильная вёрстка
+
+На ширине `≤ @screen-sm-max` (767px) фон корневого элемента и слой с пунктирной
+рамкой скрываются: перетаскивание на мобильных недоступно. Разметку под мобильный
+сценарий (заголовок + кнопка «Загрузить», вызывающая `openUploadDialog`) даёт
+потребитель — типовой приём с `MobileView` показан в stories `Default`
+и `Example: production`. На узком экране перетаскивания нет, поэтому по дизайну
+вместо области сброса показывается обычная кнопка загрузки.
+
+Список уже загруженных файлов потребитель переключает тем же `MobileView`
+отдельно от зоны: на широком экране — таблица, на узком — `List` с
+`ListTableItem` (имя, размер, статус), а действия над файлом уходят в
+`controlButtons` под свайпом. Пример — story `Example: production`.
+
+---
+
+## Дизайн-токены
+
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/UploadZone.ts`.
+
+```text
+UploadZone.Background_Default
+UploadZone.Background_Hover
+UploadZone.BorderColor_Default
+UploadZone.DragArea_Background
+UploadZone.DragArea_BorderColor
+```
+
+`Background_*` — фон корневого блока в покое и при наведении (на мобильной
+ширине фон отключён). `BorderColor_Default` — пунктирная рамка зоны в покое.
+`DragArea_*` — фон и рамка дроп-зоны, видимой во время перетаскивания.
+
+---
+
+## Инварианты
+
+- `forwardRef` на `UploadZone` — не убирать; ref всегда указывает на корневой
+  `<div class="uploadZone">`, а не на слой-перехватчик.
+- Раскладка `className` / `...rest` на слой `uploadZoneDragArea` (а не на
+  корневой элемент) — наблюдаемое поведение публичного API. Перенос их на
+  корневой `<div>` сломает существующую вёрстку потребителей.
+- `onChange` — единственный канал результата и для диалога, и для drop.
+  Добавлять отдельный `onChange` в `UploadZone.Input` нельзя: тип поля намеренно
+  исключает этот prop.
+- `UploadZoneOnChangeType` экспортируется из barrel без префикса `T`
+  (нарушение текущего naming convention) — переименование будет ломающим
+  изменением, оставлено как есть.
+- Barrel `src/components/UploadZone/index.ts` экспортирует `UploadZone`,
+  `IUploadZoneProps`, `IUploadZoneChildrenProvideProps`, `UploadZoneInput`,
+  `IUploadZoneInputProps`, `UploadZoneOnChangeType`.
+- `UploadZoneContext` — внутренняя деталь, в barrel его нет; связь
+  `UploadZone` ↔ `UploadZone.Input` можно менять свободно.
+- Класс `uploadZoneContainerDragArea` используется unit-тестами для поиска
+  смонтированной дроп-зоны — переименование требует правки тестов.
+- Дроп-зона монтируется через отдельный `createRoot` (React 18 API) — это
+  единственное место компонента, зависящее от версии React.
+
+---
+
+## Accessibility
+
+- Слой-перехватчик кликов — `<div role="none">` с `onClick`: он намеренно
+  скрыт от дерева доступности и **не управляется с клавиатуры**.
+- Поле `UploadZone.Input` скрыто через `display: none`, поэтому в таб-порядок
+  тоже не попадает.
+- Отсюда требование к потребителю: чтобы загрузка была доступна с клавиатуры
+  и скринридеру, в `children` нужен фокусируемый элемент, вызывающий
+  `openUploadDialog`.
+- Этому требованию отвечает `Button` (в том числе `theme={EButtonTheme.LINK}`,
+  если нужен вид ссылки): он рендерит `<button>` и попадает в таб-порядок.
+  **`Link` без `href` — не отвечает**: он рендерит `<a role="link">`, а такой
+  элемент браузер в таб-порядок не включает.
+- В десктопном контенте примеров stories используется `Link`, поэтому точка
+  входа в диалог там с клавиатуры недоступна. Мобильные ветки `Default`
+  и `Example: production` вызывают `openUploadDialog` из `Button` и доступны.
+  В продуктовом коде предпочитай `Button`.
+- Текстовые подписи и `aria-label` задаёт потребитель: компонент не хардкодит
+  строки на конкретном языке.
+
+---
+
+## Связанные компоненты
+
+Отдельного семейства и близких альтернатив у компонента нет — `related` пуст.
+
+- `UploadZone.Input` — составная часть, описана выше; собственного AI.md не имеет.
+- Типовые соседи в разметке (связь композиционная, не структурная): `MobileView`
+  для мобильного варианта содержимого, `TableBasic` со списком загруженных
+  файлов на широком экране и `List` / `ListTableItem` /
+  `ListItemControlsButton` — на узком, `Link` / `Button` как точка вызова
+  `openUploadDialog`, `HelpBox` с подсказкой о допустимых форматах.
+
+---
+
+## Stories
+
+Основные истории: `stories/UploadZone/UploadZone.stories.tsx`
+Файлы примеров: `stories/UploadZone/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Переключение `dropZoneContainer`, `renderContainerContent` и `multiple` |
+| `Default` | `Default.tsx` | Зона с дроп-зоной на площади внешнего контейнера; на узком экране через `MobileView` вместо неё кнопка |
+| `Production` (Example: production) | `Production.tsx` | Композиция со списком загруженных файлов: таблица на широком экране, `ListTableItem` на узком; оба варианта через `MobileView` |
+| `VisualTests` | `VisualTests.tsx` | Состояния для скриншот-тестов: покой и раскрытая дроп-зона (через `play`) |
+
+`Playground` исключён из скриншот-тестов: кадр зависит от значений controls.
+`Production` тоже исключён — пример композиционный, его кадр ловит изменения
+`TableBasic`, `List` и `MobileView`, а не самой зоны загрузки.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-09-16 | Создан документ. AI-рефакторинг: `UploadZone.Input` получил `forwardRef` и корректный `displayName`, stories переписаны на modern pattern |
+| 2026-09-18 | Правки по ревью: в примерах точка входа в диалог вернулась на `Link`, уточнён раздел Accessibility |
+| 2026-09-21 | Правки по ревью: в `Example: production` список загруженных файлов на узком экране переведён на `ListTableItem` |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/UploadZone/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    UploadZone,
+    MobileView,
+    Gap,
+    Text,
+    Link,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    EFontType,
+    ETextSize,
+} from "@sberbusiness/triplex-next";
+import { ClouddraguploadStrokeSrvIcon32 } from "@sberbusiness/icons-next";
+
+export const Default = () => {
+    /** Контейнер, на площади которого перехватывается перетаскивание файлов. */
+    const [dropZoneContainer, setDropZoneContainer] = useState<HTMLDivElement | null>(null);
+
+    const handleChange = () => {};
+
+    const renderContainerContent = () => (
+        <div
+            style={{
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                justifyContent: "center",
+                height: "100%",
+            }}
+        >
+            <ClouddraguploadStrokeSrvIcon32 paletteIndex={5} />
+            <Gap size={4} />
+            <Text type={EFontType.PRIMARY} size={ETextSize.B3} tag="div">
+                Положите файлы сюда
+            </Text>
+        </div>
+    );
+
+    /** Широкий экран: перетаскивание плюс ссылка выбора файлов. */
+    const renderDesktopContent = (openUploadDialog: () => void) => (
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "center", padding: "16px 0" }}>
+            <UploadZone.Input multiple />
+            <ClouddraguploadStrokeSrvIcon32 paletteIndex={5} />
+            <Gap size={4} />
+            <Text type={EFontType.PRIMARY} size={ETextSize.B3} tag="div">
+                Label text
+                {"\u00A0"}
+                <Link onClick={openUploadDialog}>Link text</Link>
+            </Text>
+        </div>
+    );
+
+    /** Узкий экран: перетаскивания нет, поэтому вместо области сброса — обычная кнопка. */
+    const renderMobileContent = (openUploadDialog: () => void) => (
+        <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", padding: "16px 0" }}>
+            <UploadZone.Input multiple />
+            <Text type={EFontType.PRIMARY} size={ETextSize.B3} tag="div">
+                Файлы для импорта
+            </Text>
+            <Gap size={8} />
+            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.SM} onClick={openUploadDialog}>
+                Загрузить
+            </Button>
+        </div>
+    );
+
+    return (
+        <div ref={setDropZoneContainer} style={{ position: "relative", display: "flow-root", maxWidth: "480px" }}>
+            <UploadZone
+                onChange={handleChange}
+                dropZoneContainer={dropZoneContainer}
+                renderContainerContent={renderContainerContent}
+            >
+                {({ openUploadDialog }) => (
+                    <MobileView fallback={renderDesktopContent(openUploadDialog)}>
+                        {renderMobileContent(openUploadDialog)}
+                    </MobileView>
+                )}
+            </UploadZone>
+        </div>
+    );
+};
+```
+

package/bundle/guides/codestyle.md

@@ -108,6 +108,9 @@ import { Button, EButtonTheme } from "@sberbusiness/triplex-next";
 // ✅ Внутри src/components
 import { EComponentSize } from "@sberbusiness/triplex-next/enums";
 
+// ✅ Внутренний модуль вне публичных subentry — только относительный путь
+import { setForwardedRef } from "../../helpers/setForwardedRef";
+
 // ✅ В unit-тестах можно импортировать локально, следуя паттерну файла
 import { Button } from "../Button";
 ```
@@ -116,6 +119,16 @@ import { Button } from "../Button";
 
 - В новых stories/examples, которые показывают копируемый код, импортируй публичный API из `@sberbusiness/triplex-next` или публичных subentry.
 - В unit-тестах и внутреннем коде следуй локальному паттерну файла и предпочитай ближайшие импорты для тестируемого модуля и внутренних зависимостей.
+- Алиас `@sberbusiness/triplex-next/...` внутри `src` допустим только для путей,
+  которые являются публичными subentry: `components`, `enums`, `utils`, `consts`,
+  `types`. Всё остальное — `src/helpers/`, внутренние `components/*/utils.ts`,
+  `components/*/consts.ts` и прочие непубличные модули — импортируй относительным
+  путём.
+
+Почему так: алиас настроен только на время сборки (`vite.config.ts`, `resolve.alias`),
+а `package.json` не объявляет `exports`, поэтому алиасный путь выглядит как публичный
+subentry, хотя модуль из barrel не экспортируется. Ориентир — существующий
+`src/helpers/breakpoints.ts`: он везде импортируется как `../../helpers/breakpoints`.
 
 Порядок импортов (prettier-plugin-organize-imports не используется, но придерживайся):
 
@@ -133,7 +146,9 @@ import { Button } from "../Button";
 
 - Только `.module.less` файлы — никаких глобальных стилей.
 - Имена классов — **camelCase**: `styles.secondaryLight`, `styles.iconOnly`.
-- Никаких **inline styles** в компонентах (в stories допустимо для лейаута примеров).
+- Никаких **inline styles** в компонентах за исключением:
+    - передачи CSS-переменных для динамических стилей;
+    - использования в stories для лейаута примеров.
 - **Цвета** — только через CSS-переменные токенов (`var(--triplex-next-...)`). Никаких hex/rgb.
   В стилях это правильная запись: CSS-переменные — внутренний слой токенов. А в документации
   (`*-ai.md`, тексты Storybook) токен указывается путём `{Группа}.{Токен}` — см.