@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 0.36.0-beta0

package/bundle/components/Pagination.md

@@ -1,10 +1,23 @@
 ---
 component: Pagination
 category: Navigation
-figma-node: ""
-figma-file: ""
-related: [SelectField, ButtonIcon, ButtonBase, Typography]
-tokens: []
+related:
+  - PaginationExtended
+  - PaginationNavigation
+  - PaginationNavigationButton
+  - PaginationNavigationExtended
+  - PaginationNavigationExtendedItem
+  - PaginationPageButton
+  - PaginationPageEllipsis
+  - PaginationSelect
+  - SelectField
+  - ButtonIcon
+  - ButtonBase
+tokens:
+  - --triplex-next-Pagination-PageButton_Background_Hover
+  - --triplex-next-Pagination-PageButton_Background_Active
+  - --triplex-next-Pagination-PageButton_Background_Selected
+  - --triplex-next-Pagination-PageButton_BorderColor_Focus
 stories: stories/Pagination/Pagination.stories.tsx
 version: "1.0"
 ---
@@ -13,286 +26,250 @@ version: "1.0"
 
 ## Назначение
 
-Готовая навигация по страницам с двумя композитными слотами:
-**`PaginationSelect`** (выбор количества элементов на странице) +
-**`PaginationNavigation`** (стрелки prev/next и кнопки страниц с
-ellipsis'ами). Сам `Pagination` — лишь сшивка через
-`PaginationExtended` (контейнер `<nav>`), управление условным
-рендером и проксирование props'ов.
+Составной компонент пагинации: навигация по страницам (кнопки «Назад»/«Вперёд», номера страниц, многоточия) и опциональный выбор количества элементов на странице. `Pagination` — готовая точка входа, которая собирает `PaginationSelect` и `PaginationNavigation` внутри контейнера `PaginationExtended`.
 
-`PaginationExtended` + примитивы (`PaginationNavigationExtended` /
-`Item` / `PaginationPageButton` / `PaginationPageEllipsis` /
-`PaginationNavigationButton`) экспортируются отдельно — для **кастомной
-сборки** пагинации, когда стандартная не подходит.
+Используй когда: нужно дать пользователю переход по страницам списка/таблицы, при необходимости — с выбором размера страницы.
 
-Используй когда: типичная пагинация над таблицей/списком. Для
-нестандартной — собирай из `PaginationExtended` + примитивов.
-
----
-
-## Файловая структура
-
-```text
-src/components/Pagination/
-├── Pagination.tsx                              # forwardRef; склейка Select + Navigation
-├── components/
-│   ├── PaginationExtended.tsx                  # forwardRef; <nav> wrapper
-│   ├── PaginationSelect.tsx                    # forwardRef; SelectField (size SM)
-│   ├── PaginationNavigation.tsx                # forwardRef; prev/pages/next + ellipsis
-│   ├── PaginationNavigationExtended.tsx        # forwardRef; <ul>
-│   ├── PaginationNavigationExtendedItem.tsx    # forwardRef; <li>
-│   ├── PaginationNavigationButton.tsx          # forwardRef; ButtonIcon SQUIRCLE + caret-icon
-│   ├── PaginationPageButton.tsx                # forwardRef; ButtonBase + Text B3
-│   └── PaginationPageEllipsis.tsx              # forwardRef; Text B3 "..."
-├── utils/paginationUtils.tsx                   # createPagesArray + generateRange + PAGINATION_ELLIPSIS_VALUE
-├── enums.ts                                    # EPaginationNavigationIconDirection (BACK | NEXT)
-├── index.ts                                    # Barrel: всё
-├── styles/*.module.less
-└── __tests__/
-```
-
----
-
-## Compound-структура
-
-```tsx
-<Pagination
-    paginationSelectProps={{
-        paginationLabel: "На странице",
-        value: pageSize,
-        options: [
-            { value: 10, label: "10" },
-            { value: 25, label: "25" },
-        ],
-        onChange: setPageSize,
-    }}
-    paginationNavigationProps={{
-        currentPage,
-        totalPages,
-        onCurrentPageChange: setCurrentPage,
-        boundaryCount: 1,
-        siblingCount: 1,
-    }}
-/>
-```
-
-Кастомная сборка:
-
-```tsx
-<PaginationExtended>
-    <PaginationNavigationExtended>
-        <PaginationNavigationExtendedItem>
-            <PaginationNavigationButton direction={EPaginationNavigationIconDirection.BACK} />
-        </PaginationNavigationExtendedItem>
-        <PaginationNavigationExtendedItem>
-            <PaginationPageButton isCurrent>1</PaginationPageButton>
-        </PaginationNavigationExtendedItem>
-        ...
-    </PaginationNavigationExtended>
-</PaginationExtended>
-```
+Не используй когда: данных немного и помещаются на один экран (при `totalPages <= 1` навигация не рендерится); нужна бесконечная прокрутка вместо постраничной.
 
 ---
 
 ## Варианты и props
 
-### Pagination — `IPaginationProps extends IPaginationExtendedProps`
-
-| Prop | Тип | Описание |
-|---|---|---|
-| `paginationSelectProps?` | `IPaginationSelectProps` | Если **не передан** — Select не рендерится. |
-| `paginationNavigationProps` | `IPaginationNavigationProps` | Обязателен. Если `totalPages <= 1` — Navigation не рендерится. |
-| `...IPaginationExtendedProps` | `HTMLAttributes<HTMLElement>` | На `<nav>`. |
+`Pagination` — управляемый компонент: текущая страница и размер страницы хранятся в стейте потребителя и передаются через колбэки. Компонент не хранит состояние страницы сам.
 
-### PaginationSelect — `IPaginationSelectProps`
-
-```ts
-extends Omit<ISelectFieldProps, "size" | "value">
-extends Required<Pick<ISelectFieldProps, "value">>
-```
+### `Pagination` (точка входа)
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `paginationLabel` | `ReactNode` | Лейбл слева от селекта (`<Text size=B3 id={instanceId}>`). |
-| `value` | `ISelectFieldProps["value"]` | Обязательно. |
-| `options`, `onChange`, ... | от SelectField | — |
-
-- **`size` захардкожен `EComponentSize.SM`**.
-- **`mobileTitle = paginationLabel`** — тот же текст для мобильного header'а.
-- **`targetProps.fieldLabel = ""`** — лейбл внутри SelectField очищается (label рисуется отдельно слева).
-- **`aria-labelledby={instanceId}`** + `Text id={instanceId}` — связь label ↔ control.
-- `instanceId = "Pagination-{lodash uniqueId()}"` — **SSR-небезопасно** (два рендера дадут разные id, гидрация может ругаться).
+| Prop | Тип | Обяз. | Описание |
+|---|---|---|---|
+| `paginationNavigationProps` | `IPaginationNavigationProps` | да | Настройки навигации по страницам. Навигация рендерится только при `totalPages > 1`. |
+| `paginationSelectProps` | `IPaginationSelectProps` | нет | Настройки селекта размера страницы. Если не передан — селект не отображается. |
+| `...rest` | `IPaginationExtendedProps` | — | Прокидывается в корневой `<nav>` (className, aria-атрибуты и т.д.). |
 
-### PaginationNavigation — `IPaginationNavigationProps extends HTMLAttributes<HTMLUListElement>`
+### `PaginationNavigation` props (через `paginationNavigationProps`)
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `currentPage` | `number` | — | Контролируемая текущая страница (1-based). |
-| `totalPages` | `number` | — | Всего страниц. |
-| `onCurrentPageChange` | `(page: number) => void` | — | Сеттер. |
+| `currentPage` | `number` | — | Номер текущей страницы (нумерация с 1). |
+| `totalPages` | `number` | — | Общее число страниц. |
+| `onCurrentPageChange` | `(page: number) => void` | — | Колбэк смены страницы. Вызывается с целевым номером. |
 | `boundaryCount` | `number` | `0` | Сколько страниц всегда показывать в начале и в конце. |
-| `siblingCount` | `number` | `0` | Сколько соседей слева/справа от текущей. |
-| `buttonPrevProps?` | `Omit<IPaginationNavigationButtonProps, "direction" \| "children">` | — | Доп. props на кнопку «назад». |
-| `buttonNextProps?` | `Omit<...>` | — | Доп. props на «вперёд». |
-
-- **prev disabled при `currentPage === 1`** (или `buttonPrevProps?.disabled`).
-- **next disabled при `currentPage === totalPages`** (или `buttonNextProps?.disabled`).
-- Рендерит prev → массив страниц от `createPagesArray(...)` → next.
-
-### PaginationNavigationButton — `IPaginationNavigationButtonProps`
+| `siblingCount` | `number` | `0` | Сколько соседних страниц показывать вокруг текущей. |
+| `buttonPrevProps` / `buttonNextProps` | `Omit<IPaginationNavigationButtonProps, "direction" \| "children">` | — | Доп. настройки кнопок навигации. |
 
-```ts
-extends Omit<IButtonIconProps, "shape" | "active" | "children">
-children?: never
-direction: EPaginationNavigationIconDirection
-```
-
-- Иконка: `CaretleftStrokeSrvIcon24 paletteIndex={5}`. Для `NEXT` — добавляется `styles.directionIconNext` (поворот через CSS).
-- `shape={EButtonIconShape.SQUIRCLE}` — захардкожен.
-- `children?: never` — фиксированная иконка.
-
-### PaginationPageButton — `TPaginationPageButtonProps`
-
-| Prop | Тип | Описание |
-|---|---|---|
-| `isCurrent?` | `boolean` | Подсветка текущей. **`aria-live="polite"`** при `isCurrent` — screen reader озвучит при смене. |
-| `children` | `ReactNode` | Номер страницы. |
-| `onClick` | `() => void` | Клик. |
+Логика расстановки видимых страниц и многоточий — в `utils/paginationUtils.tsx` (`PaginationUtils.createPagesArray`). При больших `totalPages` и нулевых `boundaryCount`/`siblingCount` отображается минимальный набор; увеличение этих значений раскрывает больше номеров и добавляет многоточия по краям. Места многоточий помечаются sentinel-значением `PAGINATION_ELLIPSIS_VALUE` (`-1`) в массиве страниц.
 
-- Содержимое — `<Text size=B3>`.
+### `PaginationSelect` props (через `paginationSelectProps`)
 
-### PaginationPageEllipsis — `IPaginationPageEllipsis extends HTMLAttributes<HTMLSpanElement>`
+Расширяет `ISelectFieldProps` (без `size`, с обязательным `value`) и добавляет `paginationLabel: React.ReactNode` — текст лейбла перед селектом. Размер селекта зафиксирован как `EComponentSize.SM`. `value`, `options`, `onChange` — управляются потребителем.
 
-- `<Text size=B3>...children...</Text>`. Контракт: `children = "..."` — чисто визуальный плейсхолдер.
+### Subкомпоненты для кастомной компоновки
 
-### PaginationExtended — `IPaginationExtendedProps extends HTMLAttributes<HTMLElement>`
-
-- `<nav>` контейнер. `data-tx={pkg.version}`.
-
-### PaginationNavigationExtended/Item
-
-- `<ul>` / `<li>` — семантический список для пагинации.
-
-### enums.ts
-
-- `EPaginationNavigationIconDirection.BACK | NEXT` (numeric enum: 0/1).
+Для нестандартной раскладки используется `PaginationExtended` напрямую с вложенными `PaginationNavigation` и `PaginationSelect` (см. story `Extended`). Низкоуровневые части (`PaginationNavigationExtended`, `PaginationNavigationExtendedItem`, `PaginationPageButton`, `PaginationPageEllipsis`, `PaginationNavigationButton`) экспортируются для построения полностью кастомной навигации, но обычно используются неявно через `PaginationNavigation`.
 
 ---
 
-## Ключевые особенности реализации
+## Дизайн-токены
 
-### Условный рендер слотов
+Собственные токены использует только `PaginationPageButton`:
 
-```tsx
-{paginationSelectProps && <PaginationSelect {...paginationSelectProps} />}
-{paginationNavigationProps.totalPages > 1 && <PaginationNavigation {...paginationNavigationProps} />}
+```text
+--triplex-next-Pagination-PageButton_Background_Hover
+--triplex-next-Pagination-PageButton_Background_Active
+--triplex-next-Pagination-PageButton_Background_Selected
+--triplex-next-Pagination-PageButton_BorderColor_Focus
 ```
 
-- Select — опциональный.
-- Navigation — рендерится только при `totalPages > 1` (на 1 странице — нечего листать).
-
-### `PaginationUtils.createPagesArray`
+Остальные части наследуют визуал от переиспользуемых компонентов: кнопки навигации — от `ButtonIcon`, кнопка-страница — от `ButtonBase`, селект — от `SelectField`, текст — от `Typography` (`Text`).
 
-```ts
-// startPages | (ellipsis | next page) | siblings around current | (ellipsis | prev page) | endPages
-```
-
-- `boundaryCount` — кол-во **всегда видимых** в начале/конце.
-- `siblingCount` — кол-во **соседей** вокруг текущей.
-- Если соседи примыкают к boundary — ellipsis заменяется на одну страницу (без «1 ... 2 3 4» — будет «1 2 3 4»).
-- Возвращает массив `number[]`, где **`PAGINATION_ELLIPSIS_VALUE = -1`** — sentinel для ellipsis.
-- Использует `lodash-es/range`.
+---
 
-### Sentinel `-1` для ellipsis
+## Инварианты
 
-```ts
-case PAGINATION_ELLIPSIS_VALUE: return <PaginationPageEllipsis>...</PaginationPageEllipsis>;
-default: return <PaginationPageButton>{page}</PaginationPageButton>;
-```
+- `forwardRef` на всех компонентах семейства — не убирать. Refs: `Pagination` → `HTMLSpanElement` (фактически прокидывается в корневой `<nav>` через `PaginationExtended`, ref-тип которого `HTMLElement`), `PaginationNavigation`/`PaginationNavigationExtended` → `HTMLUListElement`, `PaginationNavigationExtendedItem` → `HTMLLIElement`, `PaginationSelect` → `HTMLDivElement`, кнопки → `HTMLButtonElement`, ellipsis → `HTMLSpanElement`.
+- Публичный API не менять: имена и обязательность props (`paginationNavigationProps` — обязателен, `paginationSelectProps` — опционален), enum `EPaginationNavigationIconDirection` (`BACK`/`NEXT`), barrel-экспорты из `index.ts`.
+- Корневой DOM-элемент `Pagination`/`PaginationExtended` — `<nav>`; навигация по страницам — семантический список `<ul>/<li>`. Не менять без обсуждения: семантика участвует в accessibility-контракте.
+- Навигация рендерится только при `totalPages > 1` — поведение публичное, на него опираются потребители.
+- Логику `PaginationUtils.createPagesArray` / `generatePageRanges` / `generateRange` не менять без перегенерации `__tests__/paginationUtils.test.tsx` — там зафиксированы граничные случаи раскладки.
+- `PAGINATION_ELLIPSIS_VALUE = -1` — sentinel в массиве страниц, на него завязан рендер многоточия.
 
-- Магическое значение `-1` — публично экспортируется как `PAGINATION_ELLIPSIS_VALUE`.
+---
 
-### `aria-live="polite"` на текущей кнопке
+## Accessibility
 
-```tsx
-aria-live={isCurrent ? "polite" : undefined}
-```
+- Корень — `<nav>`, навигация — список `<ul>/<li>`, что даёт ассистивным технологиям корректную семантику пагинации.
+- Кнопки «Назад»/«Вперёд» автоматически получают `disabled` на первой/последней странице соответственно.
+- Текущая страница (`PaginationPageButton` с `isCurrent`) помечается `aria-live="polite"`, чтобы смена страницы озвучивалась скринридером.
+- `PaginationSelect` связывает лейбл и контрол через `aria-labelledby` (генерируемый `instanceId`), лейбл также используется как `mobileTitle`.
+- Текст кнопок навигации не хардкодится в компоненте — при необходимости потребитель передаёт `aria-label` через `buttonPrevProps`/`buttonNextProps` (библиотека мультиязычная).
 
-- При смене `currentPage` screen reader озвучит новую кнопку.
+---
 
-### Иконка NEXT — поворот через CSS
+## Связанные компоненты
 
-```tsx
-{isDirectionBack ? <CaretleftStrokeSrvIcon24 ... /> : <CaretleftStrokeSrvIcon24 className={styles.directionIconNext} />}
-```
+- `PaginationExtended` — контейнер `<nav>` для кастомной компоновки пагинации.
+- `PaginationNavigation` — блок навигации по страницам (используется внутри `Pagination`, доступен отдельно).
+- `PaginationSelect` — селект размера страницы поверх `SelectField`.
+- `PaginationNavigationExtended` / `PaginationNavigationExtendedItem` — список `<ul>` и его элемент `<li>` для построения кастомной навигации.
+- `PaginationPageButton` — кнопка-страница (поверх `ButtonBase`).
+- `PaginationPageEllipsis` — многоточие, заменяющее группу скрытых страниц.
+- `PaginationNavigationButton` — кнопка «Назад»/«Вперёд» (поверх `ButtonIcon`), направление задаётся `EPaginationNavigationIconDirection`.
 
-- Только одна иконка (`CaretleftStrokeSrvIcon24`); для NEXT — поворот на 180° через `styles.directionIconNext`.
+---
 
-### `aria-labelledby` через `uniqueId`
+## Stories
 
-```ts
-const [instanceId] = useState(() => `Pagination-${uniqueId()}`);
-```
+Основные истории: `stories/Pagination/Pagination.stories.tsx`
+Файлы примеров: `stories/Pagination/examples/Pagination/`
 
-- **SSR-небезопасно**: lodash `uniqueId` глобальный счётчик.
-- Решает связь Text-label ↔ SelectField через `aria-labelledby`.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `currentPage`, `totalPages`, `boundaryCount`, `siblingCount`, `hidePaginationSelect`, `paginationLabel`, `className` |
+| `Default` | `Default.tsx` | Базовая навигация без селекта (50 элементов, размер страницы 10) |
+| `WithSelectField` | `WithSelectField.tsx` | Навигация с селектом размера страницы, `boundaryCount`/`siblingCount = 1` |
+| `Extended` | `Extended.tsx` | Кастомная компоновка через `PaginationExtended` + `PaginationNavigation` + `PaginationSelect` |
+| `VisualTests` | — | Скриншот-регрессия: короткая навигация, многоточия слева/справа/с обеих сторон, disabled-крайние кнопки, вариант с селектом |
 
 ---
 
-## Инварианты
+## История изменений
 
-- **`Pagination.totalPages > 1`** — Navigation рендерится; иначе скрыт.
-- **`paginationNavigationProps`** — обязательный prop (тип, не optional).
-- **`paginationSelectProps`** — опционален; отсутствие = нет селекта.
-- **`PAGINATION_ELLIPSIS_VALUE = -1`** — публичная константа-sentinel.
-- **`PaginationSelect.size = SM`** — захардкожен.
-- **`PaginationSelect.targetProps.fieldLabel = ""`** — внутренний label очищается.
-- **`PaginationNavigationButton.shape = SQUIRCLE`**, иконка `CaretleftStrokeSrvIcon24` — фиксированы; `children: never`.
-- **`PaginationPageButton.aria-live="polite"`** при `isCurrent` — публичный a11y-контракт.
-- **`uniqueId()`** в SelectId — SSR-небезопасно.
-- **`<nav>` корень PaginationExtended** + `<ul>`/`<li>` для Navigation — семантическая структура.
-- **`createPagesArray` зависит от lodash-es `range`**.
-- **`EPaginationNavigationIconDirection`** — numeric enum (0/1), не string.
-- **ForwardRef** на всех уровнях.
+| Дата | Изменение |
+|---|---|
+| 2026-06-22 | Создан документ |
 
 ---
 
-## Accessibility
+## Примеры использования
 
-- `<nav>` корень + `<ul>`/`<li>` элементы — корректная семантика навигации/списка.
-- `aria-live="polite"` на текущей странице — озвучивание при смене.
-- `aria-labelledby` связывает label PaginationSelect с самим SelectField.
-- **Нет `aria-label="Pagination"`** на `<nav>` — потребитель должен передать через `...rest` (иначе screen reader скажет просто «navigation»).
-- **Иконки prev/next без `aria-label`** — `ButtonIcon` сам по себе не озвучивает направление. Потребитель должен передать `buttonPrevProps={{ "aria-label": "Предыдущая" }}` и т.п.
-- `disabled` корректно через `<button disabled>` — клавиатура и SR обработают.
+### Default
 
----
+`stories/Pagination/examples/Pagination/Default.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import { Pagination } from "@sberbusiness/triplex-next";
 
-Нет собственных — наследуются от `Button`, `Text`, `SelectField`.
+export const Default = () => {
+    const totalItems = 50;
+    const pageSize = 10;
+    const [page, setPage] = useState(1);
 
----
+    const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
 
-## Связанные компоненты
+    return <Pagination paginationNavigationProps={{ currentPage: page, totalPages, onCurrentPageChange: setPage }} />;
+};
+```
 
-- `SelectField` — нижележащий control в PaginationSelect.
-- `ButtonIcon`, `ButtonBase` — кнопки.
-- `Text` (Typography) — текст.
-- `CaretleftStrokeSrvIcon24` — единственная иконка стрелки.
-- `lodash-es/range`, `lodash-es/uniqueId`.
+### WithSelectField
 
----
+`stories/Pagination/examples/Pagination/WithSelectField.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { Pagination, ISelectExtendedFieldDefaultOption } from "@sberbusiness/triplex-next";
+
+export const WithSelectField = () => {
+    const [page, setPage] = useState(7);
+    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" },
+    ];
+
+    const selectedOption = options.find((option) => option.value === String(pageSize));
+
+    return (
+        <Pagination
+            paginationNavigationProps={{
+                currentPage: page,
+                totalPages,
+                boundaryCount: 1,
+                siblingCount: 1,
+                onCurrentPageChange: setPage,
+            }}
+            paginationSelectProps={{
+                paginationLabel: "Показать на странице:",
+                options,
+                value: selectedOption || options[0],
+                onChange: handlePageSizeChange,
+                targetProps: {
+                    fieldLabel: "",
+                },
+            }}
+        />
+    );
+};
+```
 
-`stories/Pagination/Pagination.stories.tsx`
-Примеры: `stories/Pagination/examples/`
+### Extended
 
----
+`stories/Pagination/examples/Pagination/Extended.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import {
+    PaginationExtended,
+    PaginationNavigation,
+    PaginationSelect,
+    ISelectExtendedFieldDefaultOption,
+} from "@sberbusiness/triplex-next";
+
+export const Extended = () => {
+    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>
+            {totalPages > 1 && (
+                <PaginationNavigation
+                    currentPage={page}
+                    totalPages={totalPages}
+                    boundaryCount={1}
+                    siblingCount={1}
+                    onCurrentPageChange={setPage}
+                />
+            )}
+            <PaginationSelect
+                paginationLabel="Показать на странице:"
+                value={selectedOption || options[0]}
+                options={options}
+                onChange={handlePageSizeChange}
+                targetProps={{
+                    fieldLabel: "",
+                }}
+            />
+        </PaginationExtended>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |

package/bundle/guides/codestyle.md

@@ -24,15 +24,15 @@
 
 ### Именование
 
-| Сущность | Префикс | Пример |
-|---|---|---|
-| Interface | `I` | `IButtonProps`, `IButtonGeneralProps` |
-| Union type | `T` | `TButtonProps` |
-| Enum | `E` | `EButtonTheme`, `EComponentSize` |
-| Константа (модульного уровня) | UPPER_SNAKE_CASE | `DEFAULT_TIMEOUT` |
-| Компонент | PascalCase | `Button`, `DateField` |
-| Хук | camelCase с `use` | `useClickOutside` |
-| Утилита | camelCase | `formatDate`, `uniqueId` |
+| Сущность                      | Префикс           | Пример                                |
+| ----------------------------- | ----------------- | ------------------------------------- |
+| Interface                     | `I`               | `IButtonProps`, `IButtonGeneralProps` |
+| Union type                    | `T`               | `TButtonProps`                        |
+| Enum                          | `E`               | `EButtonTheme`, `EComponentSize`      |
+| Константа (модульного уровня) | UPPER_SNAKE_CASE  | `DEFAULT_TIMEOUT`                     |
+| Компонент                     | PascalCase        | `Button`, `DateField`                 |
+| Хук                           | camelCase с `use` | `useClickOutside`                     |
+| Утилита                       | camelCase         | `formatDate`, `uniqueId`              |
 
 ### Интерфейсы компонента
 
@@ -113,10 +113,12 @@ import { Button } from "../Button";
 ```
 
 Правила:
+
 - В новых stories/examples, которые показывают копируемый код, импортируй публичный API из `@sberbusiness/triplex-next` или публичных subentry.
 - В unit-тестах и внутреннем коде следуй локальному паттерну файла и предпочитай ближайшие импорты для тестируемого модуля и внутренних зависимостей.
 
 Порядок импортов (prettier-plugin-organize-imports не используется, но придерживайся):
+
 1. React
 2. Сторонние библиотеки
 3. Внутренние (`@sberbusiness/triplex-next/...`)
@@ -133,9 +135,31 @@ import { Button } from "../Button";
 - Имена классов — **camelCase**: `styles.secondaryLight`, `styles.iconOnly`.
 - Никаких **inline styles** в компонентах (в stories допустимо для лейаута примеров).
 - **Цвета** — только через CSS-переменные токенов (`var(--triplex-next-...)`). Никаких hex/rgb.
+- Runtime CSS-переменные, которые компонент задаёт сам (например через `style` для динамической высоты,
+  transform или координат), называй с префиксом `--triplex-next-runtime-...`.
+  Они не являются дизайн-токенами и не должны попадать в `src/components/DesignTokens` или generated-файлы.
 - **Переиспользуемые размерные константы** (z-index, отступы страницы, ширины оверлеев) — через LESS-переменные из `src/styles/components/` (`@page-padding-desktop-x`, `@sideOverlayLGWidth` и т.д.). Компонент-специфичные значения (высота кнопки, радиус скругления) можно задавать литералом.
 - `!important` — только в крайнем случае, с комментарием почему.
 
+Паттерн runtime CSS-переменных:
+
+```text
+--triplex-next-runtime-{Component}-{Element}_{Property}
+```
+
+Примеры:
+
+```tsx
+interface IStyle extends React.CSSProperties {
+    "--triplex-next-runtime-ImageGalleryExtended-Track_Shift": string;
+}
+```
+
+```less
+.track {
+    transform: translateX(var(--triplex-next-runtime-ImageGalleryExtended-Track_Shift, 0%));
+}
+```
 
 ### Применение LESS-переменных (общие размерные константы)
 
@@ -166,7 +190,7 @@ import { Button } from "../Button";
 В stories добавляй пример значения для демонстрации — это не хардкод, а иллюстрация:
 
 ```typescript
-// В stories/examples/DefaultExample.tsx — пример для документации
+// В stories/examples/Default.tsx — пример для документации
 <ModalCloseButton aria-label="Закрыть" />
 ```
 
@@ -191,8 +215,11 @@ import { Button } from "../Button";
 ## Принципы написания кода
 
 ### DRY (Don't Repeat Yourself)
+
 ### KISS (Keep It Simple, Stupid)
+
 ### YAGNI (You Aren't Gonna Need It)
+
 ### Single Responsibility
 
 ### Не добавляй без задачи
@@ -202,4 +229,4 @@ import { Button } from "../Button";
 - Не добавляй обработку ошибок для сценариев, которые не могут произойти.
 - Не мигрируй legacy stories/tests на новый шаблон "по пути", если это не часть текущей задачи.
 
----
+---

package/bundle/guides/commits.md

@@ -86,7 +86,6 @@ npx prettier --write src/components/Button/Button.tsx
 | Файл/папка | Причина |
 |---|---|
 | `__screenshots__/` | Только из Docker/CI. Если нужно — подтвердить в pre-commit hook |
-| `.mcp.json` | Персональный токен Figma — в `.gitignore` |
 | `.env.local` | Секреты — в `.gitignore` |
 | `node_modules/`, `dist/`, `storybook-static/` | В `.gitignore` |
 
@@ -163,4 +162,4 @@ stories/release-notes/v1/<текущая версия>.mdx
 - [ ] Нет случайно добавленных файлов (`git status`)
 - [ ] Для новых локальных/временных/генерируемых файлов проверено, не нужно ли добавить правило в `.gitignore`
 - [ ] Нет скриншотов из macOS в `__screenshots__/`
-- [ ] Release notes обновлены (если изменился публичный API компонента)
+- [ ] Release notes обновлены (если изменился публичный API **или наблюдаемое поведение** компонента — не только при breaking change)