@sberbusiness/triplex-next-mcp-server 1.50.0-beta → 1.53.1

package/bundle/components/Pagination.md

@@ -3,7 +3,6 @@ component: Pagination
 category: Navigation
 related:
   - PaginationExtended
-  - PaginationNavigationExtended
   - SelectField
   - ButtonIcon
   - MasterTable
@@ -51,7 +50,7 @@ version: "1.0"
 | `siblingCount` | `number` | `0` | Сколько соседних страниц показывать вокруг текущей. |
 | `buttonPrevProps` / `buttonNextProps` | `Omit<IPaginationNavigationButtonProps, "direction" \| "children">` | — | Доп. настройки кнопок навигации. |
 
-Логика расстановки видимых страниц и многоточий — в `utils/paginationUtils.tsx` (`PaginationUtils.createPagesArray`). При больших `totalPages` и нулевых `boundaryCount`/`siblingCount` отображается минимальный набор; увеличение этих значений раскрывает больше номеров и добавляет многоточия по краям. Места многоточий помечаются sentinel-значением `PAGINATION_ELLIPSIS_VALUE` (`-1`) в массиве страниц.
+Логика расстановки видимых страниц и многоточий — в `utils.tsx` (`PaginationUtils.createPagesArray`). При больших `totalPages` и нулевых `boundaryCount`/`siblingCount` отображается минимальный набор; увеличение этих значений раскрывает больше номеров и добавляет многоточия по краям. Места многоточий помечаются sentinel-значением `PAGINATION_ELLIPSIS_VALUE` (`-1`) в массиве страниц.
 
 ### `PaginationSelect` props (через `paginationSelectProps`)
 
@@ -104,7 +103,7 @@ Pagination.PageButton_BorderColor_Focus
 - Публичный API не менять: имена и обязательность props (`paginationNavigationProps` — обязателен, `paginationSelectProps` — опционален), enum `EPaginationNavigationIconDirection` (`BACK`/`NEXT`), barrel-экспорты из `index.ts`.
 - Корневой DOM-элемент `Pagination`/`PaginationExtended` — `<nav>`; навигация по страницам — семантический список `<ul>/<li>`. Не менять без обсуждения: семантика участвует в accessibility-контракте.
 - Навигация рендерится всегда, включая случай единственной страницы: `PaginationNavigation` приводит `totalPages` к минимуму 1, рисует одну страницу и блокирует обе стрелки. Это держит высоту панели пагинации постоянной независимо от размера страницы — не возвращать условный рендер по `totalPages > 1`.
-- Логику `PaginationUtils.createPagesArray` / `generatePageRanges` / `generateRange` не менять без перегенерации `__tests__/paginationUtils.test.tsx` — там зафиксированы граничные случаи раскладки.
+- Логику `PaginationUtils.createPagesArray` / `generatePageRanges` / `generateRange` не менять без проверки `__tests__/utils.test.ts` — там зафиксированы граничные случаи раскладки.
 - `PAGINATION_ELLIPSIS_VALUE = -1` — sentinel в массиве страниц, на него завязан рендер многоточия.
 - Блокировка по `MasterTableContext.loading` перекрывает `disabled`, пришедший из props: в состоянии загрузки кнопка заблокирована независимо от того, что передал потребитель. Обратное неверно — вне загрузки решает prop.
 - `PaginationSelect` не должен терять свойства: его публичный тип — свойства `SelectField`, поэтому всё, что не разобрано явно, обязано уходить в `SelectField`. Точечные перечисления props вместо `...rest` здесь уже приводили к молчаливой потере `status`, `targetProps` и `data`-атрибутов.
@@ -133,6 +132,16 @@ Pagination.PageButton_BorderColor_Focus
 - `PaginationNavigationButton` — кнопка «Назад»/«Вперёд» (поверх `ButtonIcon`), направление задаётся `EPaginationNavigationIconDirection`.
 - `MasterTable` — таблица, в паре с которой пагинация обычно и используется (`MasterTable.PaginationPanel`). Её `loading` через `MasterTableContext` блокирует элементы пагинации.
 
+### PaginationNavigationExtended
+
+Контейнер `<ul>` для полностью кастомной компоновки навигации. Он задаёт раскладку списка, а состав страниц определяет потребитель. Для автоматического вычисления видимых страниц и многоточий используй `PaginationNavigation`. Как тривиальная обёртка `PaginationNavigationExtended` описывается здесь, отдельного AI.md у него нет.
+
+`IPaginationNavigationExtendedProps` наследует стандартные HTML-атрибуты `<ul>`. `children` передаёт содержимое списка: для сохранения семантики `<ul>/<li>` используй `PaginationNavigationExtendedItem` или обычные `<li>`. `className` объединяется с базовым классом через `clsx`, остальные HTML-свойства, включая `id`, `aria-*`, `data-*` и обработчики событий, передаются через `...rest` на корневой `<ul>`. `forwardRef` направлен на этот же элемент (`HTMLUListElement`), `displayName` равен `PaginationNavigationExtended`; корневой элемент, ref-target и публичный экспорт сохраняй.
+
+Раскладка — горизонтальный flex-список с `align-items: center` и `gap: 4px`, без маркеров (`list-style-type: none`), с нулевыми `margin` и `padding`. Собственных тем и дизайн-токенов у контейнера нет; оформление вложенных кнопок и многоточий определяется соответствующими компонентами.
+
+Контейнер не хранит состояние и не имеет собственных callback-props, не генерирует номера страниц, не обрабатывает `disabled` или `loading` и не читает `MasterTableContext`. Текущую страницу, блокировку кнопок, многоточия и переходы задают дочерние элементы и потребитель; вложенные кнопки могут сами учитывать загрузку таблицы. Для доступности потребитель задаёт имя навигации, подписи кнопок и при необходимости `aria-current="page"` на текущей странице. Управление фокусом и клавиатурное поведение остаются у вложенных элементов: контейнер не добавляет обработчиков клавиатуры или roving tabindex.
+
 ---
 
 ## Stories
@@ -148,6 +157,17 @@ Pagination.PageButton_BorderColor_Focus
 | `Extended` | `Extended.tsx` | Кастомная компоновка через `PaginationExtended` + `PaginationNavigation` + `PaginationSelect` |
 | `VisualTests` | — | Скриншот-регрессия: короткая навигация, многоточия слева/справа/с обеих сторон, disabled-крайние кнопки, вариант с селектом |
 
+### PaginationNavigationExtended
+
+Основные истории: `stories/Pagination/PaginationNavigationExtended.stories.tsx`
+Файлы примеров: `stories/Pagination/examples/PaginationNavigationExtended/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Example` | `Example.tsx` | Ручная компоновка кнопок страниц, текущей страницы, многоточия и заблокированной кнопки «Назад» внутри `PaginationExtended` |
+
+`Playground` отсутствует: у контейнера только стандартные HTML-свойства. Единственная история `Example` доступна как пример семейства `Pagination` и участвует в скриншот-тестах.
+
 ---
 
 ## История изменений
@@ -159,6 +179,8 @@ Pagination.PageButton_BorderColor_Focus
 | 2026-08-12 | В состоянии загрузки `MasterTable` элементы пагинации становятся `disabled` — читается из `MasterTableContext.loading`. Публичный API не изменился. Заодно `PaginationSelect` перестал молча терять переданный `status`. |
 | 2026-08-27 | Навигация больше не скрывается при `totalPages <= 1`: отрисовывается одна страница с заблокированными стрелками, высота панели пагинации не схлопывается. Публичный API не изменился. |
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`PaginationNavigation`, `PaginationNavigationButton`, `PaginationNavigationExtendedItem`, `PaginationPageButton`, `PaginationPageEllipsis`, `PaginationSelect`, `ButtonBase`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
+| 2026-10-07 | TRI-66: описан контракт обёртки `PaginationNavigationExtended` в родительской документации, добавлены её stories и файлы примеров; ссылка из `related` удалена, поскольку отдельный AI.md для обёртки не создаётся. |
+| 2026-10-16 | При сверке AI-Ready удалены ссылки на отсутствующие stories и примеры `Default` / `VisualTests` у `PaginationNavigationExtended`; таблица соответствует текущему `Example`, пути к утилитам и их тестам актуализированы. |
 
 ---
 
@@ -293,3 +315,59 @@ export const Extended = () => {
 };
 ```
 
+### Example
+
+`stories/Pagination/examples/PaginationNavigationExtended/Example.tsx`
+
+```tsx
+import React from "react";
+import {
+    EPaginationNavigationIconDirection,
+    PaginationExtended,
+    PaginationNavigationButton,
+    PaginationNavigationExtended,
+    PaginationNavigationExtendedItem,
+    PaginationPageButton,
+    PaginationPageEllipsis,
+} from "@sberbusiness/triplex-next";
+
+export const Example = () => (
+    <PaginationExtended aria-label="Пагинация">
+        <PaginationNavigationExtended>
+            <PaginationNavigationExtendedItem>
+                <PaginationNavigationButton
+                    direction={EPaginationNavigationIconDirection.BACK}
+                    aria-label="Предыдущая страница"
+                    disabled
+                    onClick={() => {}}
+                />
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationPageButton isCurrent aria-current="page" onClick={() => {}}>
+                    1
+                </PaginationPageButton>
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationPageButton onClick={() => {}}>2</PaginationPageButton>
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationPageButton onClick={() => {}}>3</PaginationPageButton>
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationPageEllipsis>...</PaginationPageEllipsis>
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationPageButton onClick={() => {}}>20</PaginationPageButton>
+            </PaginationNavigationExtendedItem>
+            <PaginationNavigationExtendedItem>
+                <PaginationNavigationButton
+                    direction={EPaginationNavigationIconDirection.NEXT}
+                    aria-label="Следующая страница"
+                    onClick={() => {}}
+                />
+            </PaginationNavigationExtendedItem>
+        </PaginationNavigationExtended>
+    </PaginationExtended>
+);
+```
+

package/bundle/components/PaginationExtended.md

@@ -0,0 +1,160 @@
+---
+component: PaginationExtended
+category: Navigation
+related:
+  - Pagination
+tokens: []
+stories: stories/Pagination/PaginationExtended.stories.tsx
+version: "1.0"
+---
+
+# PaginationExtended
+
+## Назначение
+
+Контейнер `<nav>` для ручной компоновки пагинации. Располагает переданные дочерние элементы в строку и центрирует их по горизонтали и вертикали.
+
+Используй когда: нужно самостоятельно выбрать состав и порядок элементов пагинации, добавить диапазон записей или собственный контрол размера страницы.
+
+Не используй когда: достаточно готовой композиции навигации и селекта — используй `Pagination`; нужна только навигация по страницам без внешнего контейнера — используй `PaginationNavigation`.
+
+---
+
+## Варианты и props
+
+Собственных вариантов, обязательных props и состояния нет. `IPaginationExtendedProps` наследует стандартные атрибуты `React.HTMLAttributes<HTMLElement>`.
+
+| Prop | Назначение |
+|---|---|
+| `children` | Состав пагинации: навигация, выбор размера страницы и дополнительные элементы. Контейнер не добавляет их самостоятельно. |
+| `className` | Дополнительный класс на корневом `<nav>`, объединяется с внутренним классом через `clsx`. |
+| Стандартные HTML-атрибуты | `aria-label`, `aria-labelledby`, `id`, `style`, обработчики и другие атрибуты передаются на корневой `<nav>`. |
+
+Текущую страницу, количество страниц, размер страницы и обработчики задаёт потребитель на дочерних компонентах. `PaginationExtended` не пересчитывает эти значения и не сбрасывает страницу при смене размера.
+
+По умолчанию контейнер не задаёт промежутки между детьми и перенос строк. Кастомную раскладку можно задать через `className` или стандартный `style`; адаптацию к узкому экрану обеспечивает потребитель.
+
+---
+
+## Дизайн-токены
+
+Собственных дизайн-токенов нет: `styles/Pagination.module.less` задаёт только позиционирование и flex-раскладку контейнера. Поэтому `tokens` в frontmatter пустой.
+
+Цвета, состояния кнопок и оформление полей относятся к дочерним компонентам. Токены кнопок страниц описаны в [Pagination-ai.md](./Pagination-ai.md), поля выбора — в [SelectField-ai.md](../SelectField/SelectField-ai.md).
+
+---
+
+## Инварианты
+
+- Сохранять `React.forwardRef<HTMLElement, IPaginationExtendedProps>`: ref указывает на корневой `<nav>`.
+- Сохранять имя `PaginationExtended`, интерфейс `IPaginationExtendedProps`, `displayName = "PaginationExtended"` и их публичный экспорт из `Pagination/index.ts`.
+- Корневой DOM-элемент — `<nav>`, внутренний класс — `paginationExtended`; `className` объединяется через `clsx`, остальные HTML-атрибуты передаются на этот же элемент.
+- Дочерние элементы рендерятся в переданном порядке. Не добавлять скрытую навигацию, селект или состояние страницы в контейнер.
+- Дефолтная раскладка — `display: flex`, `justify-content: center`, `align-items: center` и `position: relative`.
+- Сохранять существующий story ID `components-pagination--extended` в `Pagination.stories.tsx`.
+
+---
+
+## Accessibility
+
+- Нативный `<nav>` создаёт навигационную область. Передавай `aria-label` или `aria-labelledby`, чтобы обозначить её назначение; это особенно полезно при нескольких навигационных областях на странице.
+- Контейнер не задаёт локализованный текст, ARIA-состояние текущей страницы и собственные клавиатурные обработчики. Эти настройки относятся к содержимому.
+- Доступные имена иконочных стрелок передаются через `buttonPrevProps` / `buttonNextProps` у `PaginationNavigation`; собственному селекту нужен лейбл.
+- Сам контейнер не включён в порядок Tab и не управляет фокусом. Клавиатурное взаимодействие обеспечивают дочерние элементы.
+
+---
+
+## Связанные компоненты
+
+- `Pagination` — готовая композиция, которая использует `PaginationExtended` как корневой контейнер и собирает `PaginationNavigation` с опциональным `PaginationSelect`.
+- `PaginationNavigation` — управляемая навигация по страницам, которую можно передать в `children`.
+- `PaginationSelect` — готовая композиция лейбла и выбора размера страницы; также может быть дочерним элементом.
+- `PaginationNavigationExtended` и его элементы — низкоуровневые части для ручного построения списка навигации внутри контейнера.
+
+---
+
+## Stories
+
+Основные истории: `stories/Pagination/PaginationExtended.stories.tsx`
+
+Файлы примеров: `stories/Pagination/examples/PaginationExtended/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Example` | `Example.tsx` | Кастомный состав: диапазон записей, навигация и `SelectField`; перенос элементов, смена размера страницы со сбросом текущей страницы. |
+
+Playground отсутствует: у контейнера нет настраиваемых props сверх `children` и стандартных HTML-атрибутов. Единственная история `Example` участвует в скриншот-тестах на xs и xl; отдельная `VisualTests` не нужна, поскольку собственных интерактивных состояний у контейнера нет.
+
+Совместимый пример `Extended` остаётся в `stories/Pagination/Pagination.stories.tsx` с файлом `stories/Pagination/examples/Pagination/Extended.tsx`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-08 | Создан документ по TRI-65: зафиксирован композиционный контракт контейнера и добавлены самостоятельные stories с копируемыми примерами. |
+| 2026-10-16 | При сверке AI-Ready удалена ссылка на отсутствующую story и пример `Default`; таблица соответствует текущему `Example`. |
+
+---
+
+## Примеры использования
+
+### Example
+
+`stories/Pagination/examples/PaginationExtended/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    PaginationExtended,
+    PaginationNavigation,
+    PaginationSelect,
+    ISelectExtendedFieldDefaultOption,
+} from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [page, setPage] = useState(1);
+    const [pageSize, setPageSize] = useState(10);
+    const totalItems = 300;
+    const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+
+    const handlePageSizeChange = (option: ISelectExtendedFieldDefaultOption) => {
+        setPageSize(Number(option.value));
+        // Смена размера страницы меняет totalPages — возвращаемся на первую, чтобы не оказаться вне диапазона.
+        setPage(1);
+    };
+
+    const options: ISelectExtendedFieldDefaultOption[] = [
+        { id: "0", value: "10", label: "10" },
+        { id: "1", value: "20", label: "20" },
+        { id: "2", value: "50", label: "50" },
+        { id: "3", value: "100", label: "100" },
+        { id: "4", value: "300", label: "300" },
+    ];
+
+    const selectedOption = options.find((option) => option.value === String(pageSize));
+
+    return (
+        <PaginationExtended>
+            <PaginationNavigation
+                currentPage={page}
+                totalPages={totalPages}
+                boundaryCount={1}
+                siblingCount={1}
+                onCurrentPageChange={setPage}
+            />
+            <PaginationSelect
+                paginationLabel="Показать на странице:"
+                value={selectedOption || options[0]}
+                options={options}
+                onChange={handlePageSizeChange}
+                targetProps={{
+                    fieldLabel: "",
+                }}
+            />
+        </PaginationExtended>
+    );
+};
+```
+

package/bundle/components/Portal.md

@@ -86,9 +86,12 @@ version: "1.0"
 ## Связанные компоненты
 
 - `Dropdown` (`src/components/Dropdown/`) — рендерит выпадающий слой через
-  Portal в `document.body`.
+  Portal в `document.body`; мобильная версия — через `Puller`, в
+  `pullerProps.renderContainer ?? document.body`.
 - `Tooltip` (`src/components/Tooltip/`) — desktop- и mobile-реализации
-  рендерят тултип через Portal: mobile — всегда в `document.body`, desktop — в
+  рендерят тултип через Portal: mobile — через `Puller`, всегда в
+  `document.body`, desktop — в `renderContainer ?? document.body`.
+- `Puller` (`src/components/Puller/`) — рендерит шторку через Portal в
   `renderContainer ?? document.body`.
 
 ---