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

package/bundle/components/MediaWidth.md

@@ -1,11 +1,9 @@
 ---
 component: MediaWidth
-category: Utilities
-figma-node: ""
-figma-file: ""
-related: [MobileView, IslandWidget]
+category: MediaWidth
+related: [MediaMinWidth, MediaMaxWidth, MediaBetweenWidth, useMatchMedia, MobileView]
 tokens: []
-stories: ""
+stories: stories/MediaWidth/MediaWidth.stories.tsx
 version: "1.0"
 ---
 
@@ -13,157 +11,297 @@ version: "1.0"
 
 ## Назначение
 
-Набор компонентов + хук для условного рендеринга по ширине окна:
-- **`useMatchMedia(query, initial)`** — хук, обёртка над `window.matchMedia` с live-обновлением через `change`-listener.
-- **`MediaMinWidth` / `MediaMaxWidth` / `MediaBetweenWidth`** — рендерят `children` / `fallback` по результату media-query.
-- **`MediaWidth`** — универсальная обёртка; по наличию `minWidth`/`maxWidth` выбирает нужный из трёх.
-
-Используй когда: нужно рендерить разный UI на разных брейкпоинтах.
-Для бинарного "mobile vs desktop" — `MobileView`. Для стилей — CSS `@media`
-напрямую (без JS-условия).
-
----
-
-## Файловая структура
-
-```text
-src/components/MediaWidth/
-├── MediaWidth.tsx            # Компонент-диспетчер
-├── MediaMinWidth.tsx         # min-width only
-├── MediaMaxWidth.tsx         # max-width only
-├── MediaBetweenWidth.tsx     # between min and max
-├── useMatchMedia.ts          # Хук
-├── index.ts                  # Barrel (все 4 компонента + хук)
-└── __tests__/
-```
+Сервисный headless-компонент адаптивности и точка входа в семейство `MediaWidth`.
+Рендерит `children`, когда ширина окна браузера попадает в диапазон, заданный
+`minWidth` и/или `maxWidth`, и `fallback` — во всех остальных случаях.
+Собственной разметки не добавляет: в DOM попадает ровно тот элемент, который
+выбран по медиа-запросу.
+
+Сам подписку на медиа-запрос не выполняет — по набору переданных props делегирует
+рендер в `MediaBetweenWidth`, `MediaMinWidth` или `MediaMaxWidth`, а те уже
+используют `useMatchMedia`.
+
+Используй когда: на определённой ширине окна нужно отрендерить **другое дерево**
+компонентов, а не просто другие стили — мобильный вариант дропдауна вместо
+десктопного, список вместо таблицы, компактная панель вместо развёрнутой.
+
+Не используй когда:
+- Разница между ширинами чисто визуальная (отступы, шрифт, раскладка) — это
+  дешевле и надёжнее решается медиа-запросом в `*.module.less`, без
+  перемонтирования поддерева.
+- Граница — мобильная (`<768px`): для этого есть `MobileView`, частный случай с
+  `maxWidth={EScreenWidth.SM_MAX}`.
+- Нужно булево значение для props или условной разметки вокруг, а не выбор между
+  двумя готовыми элементами — используй хук `useMatchMedia` (или `useMobileView`
+  для мобильной границы).
 
 ---
 
 ## Варианты и props
 
-### MediaWidth — `IMediaProps`
+### Обязательные props
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `children` | `ReactElement \| null` | Да | Элемент рендерится при совпадении с media-query. |
-| `fallback` | `ReactElement \| null` | Да | Рендерится, если не совпало. |
-| `minWidth` | `EScreenWidth` | Нет | Нижняя граница. |
-| `maxWidth` | `EScreenWidth` | Нет | Верхняя граница. |
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactElement \| null` | Элемент для ширины внутри диапазона. `null` — внутри диапазона не рендерится ничего |
+| `fallback` | `React.ReactElement \| null` | Элемент для ширины вне диапазона. Обязателен: prop без значения по умолчанию, для «ничего» передаётся явный `null` |
 
-Логика выбора:
-- `minWidth && maxWidth` → `MediaBetweenWidth`
-- `minWidth` → `MediaMinWidth`
-- `maxWidth` → `MediaMaxWidth`
-- Ни один — возвращает `fallback`.
+### Опциональные props
 
-### MediaMinWidth / MediaMaxWidth / MediaBetweenWidth
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `minWidth` | `EScreenWidth` | — | Нижняя граница диапазона, включительно |
+| `maxWidth` | `EScreenWidth` | — | Верхняя граница диапазона, включительно |
+
+### Как комбинация props выбирает реализацию
+
+| Переданы | Делегирует в | Медиа-запрос |
+|---|---|---|
+| `minWidth` и `maxWidth` | `MediaBetweenWidth` | `(max-width: {maxWidth}) and (min-width: {minWidth})` |
+| только `minWidth` | `MediaMinWidth` | `(min-width: {minWidth})` |
+| только `maxWidth` | `MediaMaxWidth` | `(max-width: {maxWidth})` |
+| ничего | — | запрос не строится, `window.matchMedia` не вызывается |
+
+### Особенности поведения
+
+- **Без `minWidth` и `maxWidth` всегда рендерится `fallback`, а `children` — никогда.**
+  Это штатное поведение, а не деградация: ветка «нет ограничений» трактуется как
+  «условие не выполнено». Story `Fallback` фиксирует его специально. Если ширины
+  приходят из props потребителя и могут быть `undefined` — учитывай, что
+  «ограничений нет» здесь означает «показать `fallback`».
+- **Границы включительные.** Значения `EScreenWidth` подобраны парами
+  (`XS_MAX = 575px` / `SM_MIN = 576px`, `SM_MAX = 767px` / `MD_MIN = 768px` и
+  т.д.), поэтому в `minWidth` передаётся `*_MIN`, в `maxWidth` — `*_MAX`. Так
+  соседние диапазоны стыкуются без перекрытия и без «дыр» в один пиксель.
+- **Согласованность `minWidth` и `maxWidth` не проверяется.** Если `minWidth`
+  больше `maxWidth`, запрос просто никогда не сматчится и всегда будет рендериться
+  `fallback` — ни предупреждения, ни ошибки не будет.
+- **Ветки взаимоисключающие.** При пересечении границы одна ветка размонтируется,
+  вторая монтируется: локальный state, фокус, значения неконтролируемых полей и
+  текущие анимации внутри поддерева теряются. Состояние, которое должно
+  переживать смену ширины, храни выше `MediaWidth` (или передавай его как props
+  в обе ветки).
+- Значение медиа-запроса читается синхронно на первом рендере (`useMatchMedia`
+  вызывает `window.matchMedia` в инициализаторе `useState`), поэтому «мигания»
+  неправильной ветки на первом кадре нет.
+- Пересчёт при ресайзе идёт по событию `change` у `MediaQueryList`, а не по
+  `resize` окна — слушатель снимается при размонтировании и переподписывается при
+  смене строки запроса.
+- **Компонент не SSR-safe:** `window.matchMedia` вызывается на первом рендере.
+  Это поведение унаследовано от `useMatchMedia` и общее для всего семейства.
 
-Аналогичные props (`children`, `fallback`, соответствующие `min`/`max`).
+---
 
-### useMatchMedia — `(query: string, initial: boolean) => boolean`
+## Дизайн-токены
 
-| Параметр | Описание |
-|---|---|
-| `query` | Полный media-query (например, `"(max-width: 767px)"`). |
-| `initial` | Начальное значение до первого рендера — критично для SSR/первого кадра. |
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
+Границы диапазонов задаются enum `EScreenWidth` (`src/helpers/breakpoints.ts`),
+согласованным с LESS-переменными брейкпоинтов.
 
-Возвращает `true`, если query совпадает. Подписывается на `change`, возвращает актуальное значение.
+---
 
-### EScreenWidth (из `@sberbusiness/triplex-next/helpers/breakpoints`)
+## Инварианты
 
-Breakpoint-значения: `XS_MAX`, `SM_MIN`, `SM_MAX`, `MD_MIN`, `MD_MAX`, `LG_MIN`, `LG_MAX`, `XL_MIN`, и т.д. (строковые — в px). Используются как значения `minWidth`/`maxWidth`.
+- **Без `forwardRef` — осознанное исключение** из общего правила библиотеки:
+  компонент не рендерит собственный host-элемент, форвардить `ref` некуда.
+  Не добавлять и не убирать без отдельного решения — это публичный контракт.
+- **Интерфейс props называется `IMediaProps`, а не `IMediaWidthProps`.**
+  Рассинхрон с именем компонента исторический, интерфейс экспортируется из
+  barrel — переименование будет breaking change. Не «чинить» походя: только
+  отдельным решением с записью в release notes.
+- **Имена и типы props `children`, `minWidth`, `maxWidth`, `fallback`** —
+  публичное API, не менять. `fallback` остаётся обязательным: сделать его
+  опциональным можно только осознанно, это меняет контракт у потребителей.
+- **Значения `EScreenWidth`** — публичное API и общая сетка дизайн-системы. Не
+  хардкодить пиксели в props и не заводить локальные брейкпоинты.
+- **Делегирование в `MediaBetweenWidth` / `MediaMinWidth` / `MediaMaxWidth`** —
+  не инлайнить `useMatchMedia` в `MediaWidth.tsx`. Строки медиа-запросов живут
+  в трёх реализациях, и это единственное место, где они собираются.
+- **Порядок веток в `if`/`else` значим:** проверка «оба props» идёт первой,
+  иначе комбинация `minWidth + maxWidth` схлопнулась бы до одной границы.
+- **Barrel `src/components/MediaWidth/index.ts`** экспортирует все четыре
+  компонента и `useMatchMedia` — состав экспортов не сокращать.
+- Реализация остаётся React 17-совместимой (без `useId`,
+  `useSyncExternalStore` и прочих React 18-only API): код синхронизируется
+  в `release-0`.
+- **Fallback на устаревшие `addListener` / `removeListener`** в `useMatchMedia` —
+  это поддержка старых браузеров, где `MediaQueryList` не наследует `EventTarget`
+  и не имеет `addEventListener` (Safari < 14). К React 17 и синхронизации
+  в `release-0` он отношения не имеет: удалять его вместе с React 17-совместимостью
+  нельзя — это наблюдаемая регрессия у потребителей.
 
 ---
 
-## Ключевые особенности реализации
+## Accessibility
 
-### `children` / `fallback` обязательны — нет "пустого рендера"
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева.
+- Невыбранная ветка **не рендерится в DOM**, а не скрывается визуально: скринридер
+  и последовательность табуляции видят только актуальный вариант. Дублирования
+  контента для ассистивных технологий не возникает, но и «широкая» разметка на
+  узком экране недоступна.
+- Смена ветки при ресайзе удаляет из DOM сфокусированный элемент — фокус
+  переходит на `<body>`. Если это критично (открытый оверлей, форма), верни
+  фокус явно на стороне потребителя.
+- Медиа-запрос завязан на ширину окна, а не на тип ввода: на десктопе с узким
+  окном тоже рендерится «мобильная» ветка. Не завязывай на `MediaWidth` наличие
+  touch-специфичных обработчиков как единственного способа взаимодействия.
 
-```ts
-children: React.ReactElement | null;
-fallback: React.ReactElement | null;
-```
+---
 
-- Оба slot'а должны быть заданы (даже если один — `null`). Не `children?: ReactNode`.
-- **Render-props стиль "if/else"**, не "return null if mismatch".
+## Связанные компоненты
 
-### `window.innerWidth` на первом рендере — НЕ SSR-safe
+Все три реализации живут в той же папке, экспортируются из того же barrel и
+собственного AI.md не имеют — их контракт описан здесь.
+
+> **Объём AI-рефакторинга.** В рамках TRI-58 отрефакторен только `MediaWidth.tsx`:
+> соседние реализации и `useMatchMedia` были вне scope задачи. В их JSDoc
+> остаются недочёты (опечатка «ширина экран» в `MediaMaxWidth` / `MediaMinWidth` /
+> `MediaBetweenWidth`, `@param initial` без соответствующего параметра
+> в `useMatchMedia`) — семейство ещё не вычищено целиком, это отдельная задача.
+> Туда же — тест на fallback `addListener` / `removeListener`: инвариант ниже
+> запрещает его удалять, но ни один тест эту ветку не исполняет (во всех моках
+> `MediaQueryList` есть `addEventListener`).
+
+- `MediaBetweenWidth` (`src/components/MediaWidth/MediaBetweenWidth.tsx`) —
+  диапазон между двумя границами. Props: `minWidth` и `maxWidth` **обязательные**,
+  плюс `children` и `fallback`. Интерфейс `IMediaBetweenWidthProps`.
+- `MediaMinWidth` (`src/components/MediaWidth/MediaMinWidth.tsx`) — только нижняя
+  граница, `minWidth` обязателен. Интерфейс `IMediaMinWidthProps`.
+- `MediaMaxWidth` (`src/components/MediaWidth/MediaMaxWidth.tsx`) — только верхняя
+  граница, `maxWidth` обязателен. Интерфейс `IMediaMaxWidthProps`.
+- `useMatchMedia` (`src/components/MediaWidth/useMatchMedia.ts`) — хук подписки на
+  произвольный медиа-запрос, основа всего семейства. Принимает строку запроса,
+  возвращает `boolean`. Годится и для не-ширинных запросов: `CarouselButton`
+  использует его с `(pointer: coarse)`.
+- `MobileView` (`src/components/MobileView/`) — частный случай `MediaWidth` с
+  `maxWidth={EScreenWidth.SM_MAX}`, со своим AI.md. Для мобильной границы
+  используется он, а не `MediaWidth` напрямую.
+
+Разница между `MediaWidth` и тремя реализациями: у `MediaWidth` обе границы
+опциональны и выбор реализации делается за потребителя; у реализаций
+соответствующие границы обязательны. Прямое использование реализации оправдано,
+когда набор границ известен статически и «пустая» комбинация невозможна по
+построению.
+
+### Потребители внутри библиотеки
+
+Компонентом `MediaWidth`: `MobileView` (и, транзитивно, все его потребители).
+Хуком `useMatchMedia`: `CarouselButton`, `useMobileView`.
+
+В unit-тестах потребителей ветка задаётся подменой `window.matchMedia` (как в
+`MediaWidth.test.tsx` и `Dropdown.test.tsx`) либо мокированием модуля
+`useMatchMedia` (как в `IslandWidget.test.tsx`).
 
-```ts
-useMatchMedia(`(min-width: ${minWidth})`, window.innerWidth >= parseInt(minWidth));
-```
+---
 
-- `window.innerWidth` в initial-аргументе выполняется **при рендере**, не в `useEffect` — упадёт на SSR.
-- Потребители в SSR должны оборачивать в ClientOnly или подавать `false`/`true` безопасный default через свой wrapper.
+## Stories
 
-### `useMatchMedia` — `addEventListener("change")`, не deprecated `addListener`
+Основные истории: `stories/MediaWidth/MediaWidth.stories.tsx`
+Файлы примеров: `stories/MediaWidth/examples/`
 
-```ts
-mediaQueryList.addEventListener("change", handleChangeMatches);
-```
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный подбор `minWidth` / `maxWidth`, включая значение `undefined` |
+| `Default` | `DefaultExample.tsx` | Обе границы: контент виден в диапазоне 768px–1199px |
+| `MinWidth` | `MinWidthExample.tsx` | Только нижняя граница: контент от 768px и шире |
+| `MaxWidth` | `MaxWidthExample.tsx` | Только верхняя граница: контент до 1199px включительно |
+| `Fallback` | `FallbackExample.tsx` | Без границ: всегда рендерится `fallback` |
+| `Example: MobileView` | `MobileViewExample.tsx` | Связь общего случая с частным — `MobileView` вместо ручной мобильной границы |
 
-- Современный API. Safari 13.1+, Chrome 76+ — ок.
-- **Legacy `addListener` не используется** — если нужна поддержка старых Safari, нужен polyfill.
+Скриншот-тестами покрыта только story `Example: MobileView` (baseline
+`mediawidth--mobile-view-story--xs.png` и `--xl.png`): на viewport `xs` (575px)
+рендерится мобильная ветка, на `xl` (1200px) — `fallback`. Остальные stories
+помечены `testRunner: { skip: true }` — их результат целиком определяется
+шириной viewport и уже проверяется этой парой скриншотов.
 
-### `useEffect` зависит только от `query`
+---
+
+## История изменений
 
-Колбэк `handleChangeMatches` всегда зовёт `setMatches(event.matches)` — `initial` игнорируется после первого рендера.
+| Дата | Изменение |
+|---|---|
+| 2026-08-11 | Создан документ. AI-рефакторинг (TRI-58): `displayName` у `MediaWidth`, исправлены опечатки и дополнен JSDoc props и компонента, unit-тесты расширены с 7 до 19 кейсов (проверяются строки медиа-запросов, выбор реализации, `null`-ветки, переподписка и отписка). Публичный API не изменён (props, `IMediaProps`, barrel-экспорты; `forwardRef` по-прежнему осознанно отсутствует). |
 
-### `MediaBetweenWidth` query — AND двух conditions
+---
 
-```ts
-`(max-width: ${maxWidth}) and (min-width: ${minWidth})`
-```
+## Примеры использования
 
-Оба условия должны выполняться. `between` — это **пересечение**.
+### Default
 
-### `MediaWidth` — не "матчит всё" по умолчанию
+`stories/MediaWidth/examples/DefaultExample.tsx`
 
-Если ни `minWidth`, ни `maxWidth` не переданы — возвращает `fallback`. Это неочевидно: потребители могут ожидать, что пустая media-query рендерит `children`. Потому всегда **передавай хотя бы одну границу**.
+```tsx
+import React from "react";
+import { MediaWidth, EScreenWidth } from "@sberbusiness/triplex-next";
 
----
+export const DefaultExample = () => (
+    <MediaWidth
+        minWidth={EScreenWidth.MD_MIN}
+        maxWidth={EScreenWidth.LG_MAX}
+        fallback={<div>Fallback: ширина экрана за пределами диапазона 768px–1199px</div>}
+    >
+        <div>Контент виден только на экранах шириной от 768px до 1199px включительно</div>
+    </MediaWidth>
+);
+```
 
-## Инварианты
+### MinWidth
 
-- **`children` и `fallback` — обязательные `ReactElement | null`**, не `ReactNode`. Не менять на optional.
-- **`EScreenWidth` как тип `minWidth`/`maxWidth`** — потребители завязаны на брейкпоинты библиотеки; произвольные строки не принимаются.
-- **`useMatchMedia(initial)` аргумент обязателен** — отсутствие initial ломает SSR-совместимость (которая и так условная).
-- **`window.innerWidth` в initial** — legacy-approach. Не вставлять в SSR-контекст без защиты.
-- **`addEventListener("change")`** — современный API; не переключать на deprecated `addListener`.
-- **`MediaWidth` без границ → `fallback`** — документированное поведение, не менять.
+`stories/MediaWidth/examples/MinWidthExample.tsx`
 
----
+```tsx
+import React from "react";
+import { MediaWidth, EScreenWidth } from "@sberbusiness/triplex-next";
 
-## Accessibility
+export const MinWidthExample = () => (
+    <MediaWidth minWidth={EScreenWidth.MD_MIN} fallback={<div>Fallback: ширина экрана менее 768px</div>}>
+        <div>Контент виден на экранах шириной 768px и более</div>
+    </MediaWidth>
+);
+```
 
-- JS-условный рендеринг → **содержимое DOM меняется на брейкпоинте**. При переключении фокуса/viewport/скринридера это может вызвать нежелательный повторный анонс.
-- Предпочитай CSS `@media` + `display: none` там, где возможно: DOM стабилен, скринридеры видят весь контент (если это желаемое поведение) или выбираешь, какой показать через `aria-hidden`.
-- Используй `MediaWidth`/`MobileView` только тогда, когда действительно нужно **разное дерево React'а** (разные компоненты, не CSS-вариации).
+### MaxWidth
 
----
+`stories/MediaWidth/examples/MaxWidthExample.tsx`
 
-## Дизайн-токены
+```tsx
+import React from "react";
+import { MediaWidth, EScreenWidth } from "@sberbusiness/triplex-next";
 
-Нет. Брейкпоинты — `EScreenWidth` (строковые px).
+export const MaxWidthExample = () => (
+    <MediaWidth maxWidth={EScreenWidth.LG_MAX} fallback={<div>Fallback: ширина экрана более 1199px</div>}>
+        <div>Контент виден на экранах шириной до 1199px включительно</div>
+    </MediaWidth>
+);
+```
 
----
+### Fallback
 
-## Связанные компоненты
+`stories/MediaWidth/examples/FallbackExample.tsx`
 
-- `MobileView` — частный случай (mobile vs desktop), use-case определён.
-- `IslandWidget` — использует `useMatchMedia` для адаптивного сворачивания.
-- `helpers/breakpoints.EScreenWidth` — источник брейкпоинтов.
+```tsx
+import React from "react";
+import { MediaWidth } from "@sberbusiness/triplex-next";
 
----
+export const FallbackExample = () => (
+    <MediaWidth fallback={<div>Fallback отображается всегда, если не заданы minWidth и maxWidth</div>}>
+        {null}
+    </MediaWidth>
+);
+```
 
-## Stories
+### Example: MobileView
 
-Нет. Компонент утилитарный; покрытие в тестах и через потребителей.
+`stories/MediaWidth/examples/MobileViewExample.tsx`
 
----
+```tsx
+import React from "react";
+import { MobileView } from "@sberbusiness/triplex-next";
 
-## История изменений
+export const MobileViewExample = () => (
+    <MobileView fallback={<div>Десктоп: ширина экрана 768px и более</div>}>
+        <div>Мобильный: ширина экрана менее 768px</div>
+    </MobileView>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |