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

package/bundle/components/ChipGroup.md

@@ -1,9 +1,7 @@
 ---
 component: ChipGroup
 category: Chips
-figma-node: ""
-figma-file: ""
-related: [Chip, TagGroup]
+related: [Chip]
 tokens: []
 stories: stories/Chips/ChipGroup.stories.tsx
 version: "1.0"
@@ -13,162 +11,120 @@ version: "1.0"
 
 ## Назначение
 
-Контейнер для набора `Chip` (и любых `Chip*`-вариантов). Управляет
-расстоянием между чипами (`gap` по size), способом переноса (`flex-wrap`)
-или горизонтальным скроллом (`oneLine`), и скрывает скроллбар.
+Контейнер-раскладка для чипсов: расставляет `Chip` и его варианты во flex-строку
+с одинаковым отступом и решает, переносятся они на новые строки или выстраиваются
+в одну строку с горизонтальной прокруткой.
 
-Это **layout-only** обёртка: не передаёт `size` детям, не синхронизирует
-disabled/selected — только стайлит контейнер. Размер чипов потребитель
-задаёт на каждом Chip индивидуально (но обычно ставит тот же, что в
-ChipGroup).
-
-Используй когда: есть 2+ чипа в одной строке или блоке фильтров.
-Не используй когда: один чип (без обёртки он тоже валиден); нужен вертикальный
-список (ChipGroup только горизонтальный); нужны теги-метки — бери `TagGroup`.
+Используй когда: на экране идёт ряд однотипных чипсов-фильтров или тегов-действий —
+`ChipGroup` рекомендуемая обёртка для любого члена семейства Chip*.
+Не используй когда: нужен контейнер общего назначения с отступами — бери собственную
+вёрстку (`Gap` для этого не годится: он принимает `Omit<..., "children">` и рендерит
+пустой разделитель фиксированной высоты), или группируются `Tag` — у них своя группа
+`TagGroup`.
 
 ---
 
-## Файловая структура
-
-```text
-src/components/ChipGroup/
-├── ChipGroup.tsx                       # React.forwardRef
-├── index.ts                            # Barrel
-└── styles/ChipGroup.module.less        # flex + oneLine (hidden scrollbar) / multiLine (wrap)
-```
-
-Особенности:
-- **Нет `__tests__`**, нет subcomponents — компонент максимально тонкий.
-- **`size` — prop, но НЕ форвардится детям**. Влияет только на `gap`.
-  Размер чипов — ответственность потребителя.
+## Варианты и props
 
----
+### Обязательные props
 
-## Варианты и props
+Обязательных props нет — `ChipGroup` работает без единого аргумента.
 
-### `IChipGroupProps extends React.HTMLAttributes<HTMLDivElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `oneLine` | `boolean` | `false` | `true` → `flex` + `overflow: auto` (горизонтальный скролл, скроллбар скрыт). `false` → `flex-wrap: wrap` (многострочный). |
-| `size` | `EComponentSize` | `MD` | Управляет gap: SM=8px, MD=8px, LG=12px. **Не передаётся в Chip.** |
-| `children` | `ReactNode` | — | Обычно набор Chip/ChipIcon/ChipSelect etc. |
-| `className` | `string` | — | Dop class через `clsx`. |
-| `...HTMLDivAttributes` | — | — | Все стандартные. |
+| `size` | `EComponentSize` | `MD` | Отступ между чипсами: `LG` — 12px, `MD` и `SM` — 8px |
+| `oneLine` | `boolean` | `false` | Одна строка с горизонтальной прокруткой вместо переноса |
+| `children` | `React.ReactNode` | — | Обычно набор `Chip`, `ChipIcon`, `ChipSelect` и других членов семейства |
+| `...HTMLDivAttributes` | `React.HTMLAttributes<HTMLDivElement>` | — | Все атрибуты `<div>`, включая `style`, `role`, `aria-*`, `data-*` |
+
+### Ограничения использования
+
+- **`size` не пробрасывается в чипсы.** Он задаёт только `gap` контейнера; размер
+  самих чипсов потребитель выставляет на каждом `Chip` отдельно (так сделано во всех
+  примерах stories). Рассинхрон `size` группы и `size` чипсов ничем не подсвечивается.
+- **`SM` и `MD` дают одинаковый отступ 8px** — визуально различимы только `LG` и остальные.
+- **`oneLine` прячет полосу прокрутки** (`scrollbar-width: none`, `-ms-overflow-style: none`,
+  `::-webkit-scrollbar { display: none }`), сама прокрутка остаётся. Пользователю нужен
+  другой аффорданс — жест, стрелки-кнопки или обрезка контента по краю.
+- **В режиме `oneLine` дети не должны сжиматься.** `flex-shrink: 0` задан только классом
+  `.chip`, то есть гарантирован у `Chip` и его прямых обёрток `ChipIcon` и `ChipOptions` —
+  они уезжают за границу и прокручиваются. У остальных членов семейства (`ChipSelect`,
+  `ChipMultiselect`, `ChipSort`, `ChipSuggest`, `ChipDatePicker`) корневой элемент несёт
+  только `.chipGroupItem` без `flex-shrink`, как и произвольный ребёнок, — такой элемент
+  сожмётся вместо прокрутки.
+- **Ширину контейнер не ограничивает.** В `oneLine` прокрутка появится, только если ширину
+  задал потребитель или родитель (в stories это `style={{ maxWidth: 360 }}`).
+- **`data-tx` выставляется после `{...rest}`** — версию библиотеки в этом атрибуте
+  переопределить нельзя, в отличие от остальных атрибутов.
 
 ---
 
-## Ключевые особенности реализации
-
-### `oneLine` → горизонтальный скролл со скрытым скроллбаром
-
-```less
-&.oneLine {
-    overflow: auto;
-    scrollbar-width: none;
-    -ms-overflow-style: none;
-    &::-webkit-scrollbar { display: none; }
-}
-```
-
-Скроллбар скрыт во всех браузерах. Пользователь скроллит свайпом (touch)
-или shift+wheel. **Без отдельной кнопки "стрелка"** — в отличие от
-`CarouselExtended`. Если нужны стрелки — оборачивай ChipGroup в
-`CarouselExtended`.
-
-### `multiLine` по умолчанию
-
-```less
-&.multiLine { flex-wrap: wrap; }
-```
-
-Без wrap — инлайновые чипы проталкивали бы родителя в overflow. Multi-line
-— стандартное поведение фильтров.
-
-### `gap` зависит от size
-
-- SM / MD: 8px
-- LG: 12px
-
-SM и MD одинаковы — это дизайн-решение. **Не объединять** в `& { gap: 8px }`
-и `&.lg { gap: 12px }` — поменяет интенсивность спецификации, может
-сломать override'ы потребителей.
-
-### `createSizeToClassNameMap(styles)` — тот же паттерн
-
-Тот же `classNameMaps.ts` утилита, что в Badge / Chip / многих других.
-Если добавить XS/XL в EComponentSize — нужно обновить и mapping, и LESS.
-
-### `data-tx={process.env.npm_package_version}` — есть
-
-Стандарт библиотеки. Не удалять.
-
-### size не передаётся детям
+## Дизайн-токены
 
-**Это отличие от многих других групповых компонентов** (CheckboxXGroup/YGroup
-передают size через контекст). ChipGroup намеренно не передаёт — потребители
-могут иметь чипы разных размеров в одной группе (например, ChipIcon LG +
-Chip MD — визуально смотрится как отдельная подсвеченная кнопка).
+Компонент не использует собственных CSS-переменных: в стилях только раскладка
+(`display: flex`, `flex-wrap`, `gap`, `overflow`). Цвета и размеры приходят от вложенных
+чипсов.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef`** — обязателен.
-- **`display: flex`** на root — не менять на grid. Потребители могут
-  полагаться на flex-item поведение чипов (`styles.chipGroupItem`
-  декларирует `display: inline-block`).
-- **Скрытый скроллбар в `oneLine`** — три вендор-префикса, не удалять.
-- **`gap` только на root-класе `.chipGroup`** — дети (чипы) не должны
-  иметь собственных margin'ов.
-- **`size` не прокидывается детям** — осознанное решение. Не добавлять
-  контекст "для консистентности".
-- **`data-tx`** — не удалять.
+- **`forwardRef`** — обязателен, `ref` указывает на корневой `<div>`. Не убирать.
+- **Корневой элемент — `<div>` без собственной роли.** Роль и ARIA-подписи — зона
+  ответственности потребителя, компонент их не навязывает.
+- **`className` и `{...rest}` уходят на тот же корневой `<div>`, что и `ref`.** `className`
+  добавляется последним аргументом `clsx` и собственные классы не затирает.
+- **Классы `.oneLine` и `.multiLine` взаимоисключающие** — ровно один из них есть всегда.
+  На это опираются unit-тесты `__tests__/ChipGroup.test.tsx`.
+- **Публичный API** — `ChipGroup`, `IChipGroupProps` через `src/components/ChipGroup/index.ts`
+  и общий barrel `src/components/index.ts`. Сохранять.
+- **`EComponentSize`** — общий enum из `src/enums/EComponentSize`, локального аналога не заводить.
+- **Story ids `chips-chipgroup--*`** завязаны на baseline-скриншоты в `__screenshots__/` —
+  переименование story требует синхронного обновления baseline.
 
 ---
 
 ## Accessibility
 
-- **Нет ARIA-ролей** — ChipGroup семантически нейтрален. Если это набор
-  фильтров — потребитель может обернуть в `<fieldset>` с `<legend>` или
-  добавить `role="group"` + `aria-label`.
-- **Клавиатурная навигация** — **не реализована**. Tab перемещается
-  линейно через tabbable-чипы внутри. Arrow keys не поддерживаются. Если
-  нужен roving-tabindex с arrow keys — это задача потребителя (или бери
-  `RadioGroup`/`TabsLine`-семейства).
-- **Скроллбар в oneLine скрыт визуально**, но работает клавиатурой (можно
-  кликнуть в ChipGroup и использовать arrow-left/right для скролла). Screen
-  reader-ы обычно читают содержимое независимо от видимости скроллбара.
-
----
-
-## Дизайн-токены
-
-Нет. Компонент структурный — gap'ы жёстко в LESS.
+- Компонент — чисто визуальный контейнер: не задаёт роль, не перехватывает клавиатуру
+  и не управляет фокусом. Семантика остаётся на вложенных чипсах (`<span role="button">`).
+- Если ряд чипсов логически является группой контролов, потребитель сам передаёт
+  `role="group"` (или `role="toolbar"`) и `aria-label` / `aria-labelledby` через `...rest` —
+  библиотека мультиязычная, текст внутри не хардкодится.
+- **Режим `oneLine` создаёт прокручиваемую область без видимой полосы.** Чтобы контент
+  оставался доступным с клавиатуры, потребителю стоит либо оставить чипсы фокусируемыми
+  (по умолчанию так и есть — прокрутка следует за фокусом), либо сделать сам контейнер
+  фокусируемым (`tabIndex={0}` с ролью и подписью).
 
 ---
 
 ## Связанные компоненты
 
-- `Chip` и все `Chip*` варианты (`src/components/Chip`) — типичные дети.
-- `TagGroup` (`src/components/Tag`) — аналогичный контейнер для тегов
-  (разная стилистика и семантика).
-- `CarouselExtended` — может обёртывать ChipGroup для добавления стрелок
-  prev/next при `oneLine` overflow.
-- `EComponentSize`, `createSizeToClassNameMap` — общий паттерн.
+- `Chip` (`src/components/Chip`) — основной ребёнок группы; вместе с ним внутрь кладут
+  `ChipIcon`, `ChipOptions`, `ChipSort`, `ChipSelect`, `ChipMultiselect`, `ChipSuggest`,
+  `ChipDatePicker` — элемент верхнего уровня у каждого из них помечен классом
+  `.chipGroupItem` (у `ChipIcon` и `ChipOptions` — через вложенный `Chip`)
+- `ListMaster.ChipGroup` (`src/components/ListMaster/components/ListMasterChipGroup.tsx`) —
+  обёртка над `ChipGroup` с фиксированным `oneLine` и горизонтальными отступами страницы;
+  собственного AI.md не имеет, описана в `ListMaster-ai.md`
+- `TagGroup` — аналогичный контейнер для `Tag`; отличается ролью `role="group"` и
+  обязательным `size`
 
 ---
 
 ## Stories
 
-`stories/Chips/ChipGroup.stories.tsx`
-Примеры: `stories/Chips/examples/ChipGroup/`
+Основные истории: `stories/Chips/ChipGroup.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipGroup/`
 
-Типовые stories:
-- `Default` — многострочный набор чипов
-- `OneLine` — горизонтальный скролл
-- `Sizes` — MD vs LG gap
-- `Playground` — интерактивный контроль `oneLine` и `size`
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` и `oneLine` |
+| `Default` | `DefaultExample.tsx` | Перенос чипсов по строкам при ограниченной ширине |
+| `Sizes` | `SizesExample.tsx` | Отступы для размеров SM / MD / LG |
+| `OneLine` | `OneLineExample.tsx` | Одна строка с горизонтальной прокруткой |
 
 ---
 
@@ -176,4 +132,117 @@ Chip MD — визуально смотрится как отдельная по
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-19 | Создан документ (TRI-27, AI-Ready Phase 1) |
+| 2026-08-19 | AI-рефакторинг (TRI-27): JSDoc на props и компоненте, маппинг размеров в UPPER_SNAKE_CASE, эквивалентное упрощение `clsx`, добавлены unit-тесты `__tests__/ChipGroup.test.tsx`. Публичный API, DOM и внешний вид не изменены |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipGroup/DefaultExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Chip, ChipGroup } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [selected, setSelected] = useState<number | null>(null);
+    const chips = ["Alpha", "Beta", "Gamma", "Delta"];
+    return (
+        <ChipGroup style={{ maxWidth: 360 }}>
+            {chips.map((label, index) => (
+                <Chip key={label} selected={selected === index} onClick={() => setSelected(index)}>
+                    {label}
+                </Chip>
+            ))}
+        </ChipGroup>
+    );
+};
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipGroup/SizesExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Chip, ChipGroup, EComponentSize } from "@sberbusiness/triplex-next";
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+type SizeItemChipProps = Pick<SizeItemProps, "size"> & {
+    name: string;
+};
+
+const SizeItemChip = ({ size, name }: SizeItemChipProps) => {
+    const [selected, setSelected] = useState(false);
+
+    const handleClick = () => setSelected((prevSelected) => !prevSelected);
+
+    return (
+        <Chip size={size} selected={selected} onClick={handleClick}>
+            {name}
+        </Chip>
+    );
+};
+
+const NAMES = ["Alpha", "Beta", "Gamma", "Delta"];
+
+const SizeItem = ({ size, label }: SizeItemProps) => (
+    <div>
+        <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+        <ChipGroup size={size}>
+            {NAMES.map((name) => (
+                <SizeItemChip key={name} size={size} name={name} />
+            ))}
+        </ChipGroup>
+    </div>
+);
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### OneLine
+
+`stories/Chips/examples/ChipGroup/OneLineExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Chip, ChipGroup, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const OneLineExample = () => {
+    const [selected, setSelected] = useState<number | null>(null);
+    const chips = Array.from({ length: 20 }, (_, i) => `Item ${i + 1}`);
+    return (
+        <ChipGroup oneLine style={{ maxWidth: 360 }}>
+            {chips.map((label, index) => (
+                <Chip
+                    key={label}
+                    size={EComponentSize.MD}
+                    selected={selected === index}
+                    onClick={() => setSelected(index)}
+                >
+                    {label}
+                </Chip>
+            ))}
+        </ChipGroup>
+    );
+};
+```
+

package/bundle/components/LightBox.md

@@ -126,6 +126,11 @@ version: "1.0"
   последнего (при переключении роутов второй лайтбокс может смонтироваться раньше, чем
   размонтируется первый). Аналогичный счётчик в `LightBoxViewManager` управляет классами
   mount-ноды (`LightBoxMountNodeViewManager`, `LB-*`).
+- **Локальные z-index внутри лайтбокса** (стековый контекст создаёт `.lightBox`): контролы и
+  sticky-шапка/футер `Page` — 100/101, лоадеры `LightBox.Content` и `LightBox.SideOverlay` — 201,
+  `TopOverlay` — 500. `LoaderScreen` приходит с глобальным `@z-index-loader-screen` (10100), поэтому
+  обе обёртки лоадера обязаны переопределять его локальным значением — иначе лоадер перекрывает
+  `TopOverlay`.
 - Баррел `index.ts` реэкспортирует `LightBox`, `enums`, `LightBoxSideOverlay` — сохранять.
 - React 17 совместимость (синхронизация в release-0): React 18-only API не использовать.
 
@@ -194,6 +199,7 @@ version: "1.0"
 | 2026-07-22 | Создан документ (Phase 1 AI-Ready). В том же изменении — AI-рефакторинг: JSDoc на props, общий `LightBoxArrow` для Prev/Next, хук `useLightBoxSidebarVisibility` для сайдбаров, устранение eslint-подавлений; публичный API не менялся |
 | 2026-07-22 | Добавлен `export` к props-интерфейсам `ILightBoxControlsProps`, `ILightBoxCloseProps`, `ILightBoxPrevProps`, `ILightBoxNextProps`, `ILightBoxSideOverlayLoaderProps` (аддитивно, для консистентности с остальными интерфейсами компонента) |
 | 2026-07-22 | Багфиксы по ревью PR #474: клавиатурные триггеры контролов целятся в видимую кнопку (стрелки не работали на desktop, Esc — на mobile); таймер-хак блокировки скролла заменён счётчиком смонтированных лайтбоксов; `LightBoxViewManager` снимает классы mount-ноды при размонтировании последнего менеджера |
+| 2026-08-17 | Исправлено: `LightBox.TopOverlay` перекрывался лоадером `LightBox.Content`. У `.loadingContentOverlay` теперь локальный z-index (201) — выше sticky-шапки и футера `Page`, но ниже `TopOverlay` (500); раньше `LoaderScreen` шёл с глобальным `@z-index-loader-screen` (10100) |
 
 ---
 

package/bundle/components/MediaWidth.md

@@ -1,7 +1,7 @@
 ---
 component: MediaWidth
 category: MediaWidth
-related: [MediaMinWidth, MediaMaxWidth, MediaBetweenWidth, useMatchMedia, MobileView]
+related: [MediaMinWidth, MediaMaxWidth, MediaBetweenWidth, useMatchMedia, MobileView, WindowResizeListener]
 tokens: []
 stories: stories/MediaWidth/MediaWidth.stories.tsx
 version: "1.0"
@@ -176,6 +176,11 @@ version: "1.0"
 - `MobileView` (`src/components/MobileView/`) — частный случай `MediaWidth` с
   `maxWidth={EScreenWidth.SM_MAX}`, со своим AI.md. Для мобильной границы
   используется он, а не `MediaWidth` напрямую.
+- `WindowResizeListener` (`src/components/WindowResizeListener/`) — альтернатива
+  для императивного случая: даёт колбэк на поток событий `resize`, а не рендерит
+  ветку по медиа-запросу. Правило выбора: нужно **что-то показать** на
+  определённой ширине — `MediaWidth`; нужно **что-то посчитать/сделать** на
+  ресайз — `WindowResizeListener`.
 
 Разница между `MediaWidth` и тремя реализациями: у `MediaWidth` обе границы
 опциональны и выбор реализации делается за потребителя; у реализаций
@@ -220,6 +225,7 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-08-18 | TRI-104: в `related` и «Связанные компоненты» добавлен `WindowResizeListener` — обратная сторона симметричной связи-альтернативы. Код и публичный API не затронуты. |
 | 2026-08-11 | Создан документ. AI-рефакторинг (TRI-58): `displayName` у `MediaWidth`, исправлены опечатки и дополнен JSDoc props и компонента, unit-тесты расширены с 7 до 19 кейсов (проверяются строки медиа-запросов, выбор реализации, `null`-ветки, переподписка и отписка). Публичный API не изменён (props, `IMediaProps`, barrel-экспорты; `forwardRef` по-прежнему осознанно отсутствует). |
 
 ---

package/bundle/components/Notification.md

@@ -202,7 +202,13 @@ export const Status = () => (
                     <Notification.Body.Content>
                         This message provides context or highlights important information to note.
                     </Notification.Body.Content>
-                    <Notification.Body.List values={Array.from({ length: 3 }, () => "List item text;")} />
+                    <Notification.Body.List
+                        items={[
+                            { key: "1", children: "List item text" },
+                            { key: "2", children: "List item text" },
+                            { key: "3", children: "List item text" },
+                        ]}
+                    />
                 </Notification.Body>
                 <Notification.Close onClick={() => {}} />
             </Notification>
@@ -218,7 +224,13 @@ export const Status = () => (
                     <Notification.Body.Content>
                         This message provides context or highlights important information to note.
                     </Notification.Body.Content>
-                    <Notification.Body.List values={Array.from({ length: 3 }, () => "List item text;")} />
+                    <Notification.Body.List
+                        items={[
+                            { key: "1", children: "List item text" },
+                            { key: "2", children: "List item text" },
+                            { key: "3", children: "List item text" },
+                        ]}
+                    />
                 </Notification.Body>
                 <Notification.Close onClick={() => {}} />
             </Notification>
@@ -234,7 +246,13 @@ export const Status = () => (
                     <Notification.Body.Content>
                         This message provides context or highlights important information to note.
                     </Notification.Body.Content>
-                    <Notification.Body.List values={Array.from({ length: 3 }, () => "List item text;")} />
+                    <Notification.Body.List
+                        items={[
+                            { key: "1", children: "List item text" },
+                            { key: "2", children: "List item text" },
+                            { key: "3", children: "List item text" },
+                        ]}
+                    />
                 </Notification.Body>
                 <Notification.Close onClick={() => {}} />
             </Notification>