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

package/bundle/components/OrderedList.md

@@ -1,9 +1,7 @@
 ---
 component: OrderedList
-category: Typography
-figma-node: ""
-figma-file: ""
-related: [UnorderedList, Typography, Text]
+category: OrderedList
+related: [UnorderedListExtended, UnorderedList]
 tokens: []
 stories: stories/OrderedList/OrderedList.stories.tsx
 version: "1.0"
@@ -13,157 +11,196 @@ version: "1.0"
 
 ## Назначение
 
-Семантический нумерованный список — `<ol>` с собственной нумерацией через
-CSS counter (а не нативные list-style-маркеры). Это даёт контроль над
-типографикой нумерации и позиционированием. Элементы — `<li>` с
-типографикой `Text size=B3`. Поддерживает `start` (с какой цифры начать).
+Нумерованный типографический список с составным JSX-API: корневой `OrderedList`
+рендерит `<ol>`, а `OrderedList.Item` — `<li>` с текстом и номером.
+Номера рисует CSS-счётчик, начальное значение задаётся через `start`.
 
-Используй когда: нужен пронумерованный список с типографикой проекта.
-Для маркированного — `UnorderedList`.
+Используй когда: порядок пунктов важен, а содержимое списка удобно собирать JSX-ом.
 
----
+Не используй когда:
 
-## Файловая структура
-
-```text
-src/components/OrderedList/
-├── OrderedList.tsx      # forwardRef<HTMLOListElement> + Object.assign({Item})
-├── OrderedListItem.tsx  # forwardRef<HTMLLIElement>
-├── types.ts             # IOrderedListProps, IOrderedListItemProps
-├── index.ts             # Barrel
-├── styles/
-│   ├── OrderedList.module.less       # counter-reset
-│   └── OrderedListItem.module.less   # counter-increment + ::before
-└── __tests__/
-```
-
----
-
-## Compound-структура
-
-```tsx
-<OrderedList start={5}>
-    <OrderedList.Item>Пятый</OrderedList.Item>
-    <OrderedList.Item>Шестой</OrderedList.Item>
-</OrderedList>
-```
-
-`OrderedList.Item` — единственный валидный child.
+- Нужны маркеры вместо номеров — используй `UnorderedListExtended` для JSX-композиции
+  или `UnorderedList` для массива данных.
+- Нужны строки с действиями, выделением или сортировкой — используй семейство `List`.
 
 ---
 
 ## Варианты и props
 
-### `IOrderedListProps extends React.OlHTMLAttributes<HTMLOListElement>`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `start` | `number` | — | С какой цифры начать (как у нативного `<ol>`). Влияет на CSS-counter (`--start-index-tx = start - 1`). |
-| `...OlHTMLAttributes` | — | — | Все атрибуты `<ol>`. |
+### Обязательные props
 
-### `IOrderedListItemProps extends React.LiHTMLAttributes<HTMLLIElement>`
+Обязательных props нет: `<OrderedList />` рендерит пустой `<ol>`.
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `...LiHTMLAttributes` | — | Все атрибуты `<li>`. |
+### Опциональные props
 
-Внутри: `<Text tag="li" size=B3>` — типографика B3 фиксирована.
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Пункты списка, обычно `OrderedList.Item`. |
+| `start` | `number` | 1 | Начальный номер. Для нумерации передавай целое число; поддерживаются ноль и отрицательные значения. |
+| `className` | `string` | — | Дополнительный класс корневого `<ol>`. |
+| `style` | `React.CSSProperties` | — | Пользовательские стили корневого `<ol>`. |
+
+`IOrderedListProps` наследует стандартные атрибуты `<ol>`, включая `aria-*`,
+`data-*` и обработчики событий. Отдельных тем и размеров у списка нет.
+
+### Нумерация и объединение стилей
+
+- При заданном `start` компонент передаёт его в HTML-атрибут и устанавливает
+  runtime-переменную `--triplex-next-runtime-OrderedList-Root_CounterReset` в `start - 1`.
+  Каждый `OrderedList.Item` увеличивает счётчик перед отображением номера.
+- Остальные свойства `style` сохраняются, runtime-переменная записывается поверх них.
+- Без `start` объект `style` передаётся без дополнений, а счётчик берёт значение 0
+  из класса самого списка — поэтому вложенный список не наследует сброс родителя.
+  После удаления `start` при повторном рендере inline-переменная удаляется.
+- Номер добавляется стилями `OrderedList.Item`; произвольный `<li>` без этих стилей
+  не получает нарисованный компонентом номер.
+- Стандартные `reversed`, `type` и `value` у пункта пробрасываются в DOM, но не
+  управляют собственным CSS-счётчиком. Обратная, буквенная нумерация и отдельный
+  номер пункта этим компонентом не реализованы.
 
 ---
 
-## Ключевые особенности реализации
-
-### Нумерация — через CSS counter, не нативный list-style
+## Дизайн-токены
 
-```less
-.orderedList {
-    --start-index-tx: 0;
-    list-style: none;
-    counter-reset: list-item-tx var(--start-index-tx);
-}
-.orderedListItem {
-    counter-increment: list-item-tx;
-    &::before { content: counter(list-item-tx) "."; ... }
-}
-```
+Собственных дизайн-токенов нет (`tokens: []`): стили списка задают отступы и
+CSS-счётчик. `--triplex-next-runtime-OrderedList-Root_CounterReset` — runtime-переменная
+нумерации по паттерну `docs/ai/codestyle.md`: не дизайн-токен и не публичный API,
+через `ThemeProvider` не переопределяется.
+Текст пункта оформляет `Text` с `ETextSize.B3`; его темизация описана в
+[`Text-ai.md`](../Typography/Text-ai.md).
 
-- **`list-style: none`** + `::before` с `counter()` — позволяет полностью контролировать визуал нумерации (font, цвет, позиционирование).
-- **`+ .orderedListItem { margin-top: 8px }`** — gap между соседними items.
-- **`position: absolute; left: 0`** на `::before` — нумерация ровняется по левому краю; `padding-left: 25px` на `<ol>` оставляет место.
+---
 
-### `start` через CSS-переменную
+## Инварианты
 
-```tsx
-style={start !== undefined ? { ...style, "--start-index-tx": start - 1 } : style}
-```
+- Сохраняй `forwardRef`: ref списка указывает на корневой `<ol>`.
+- Сохраняй составной API `OrderedList.Item` и отдельный экспорт `OrderedListItem`.
+  Пункт рендерится как `<li>`, его ref указывает на этот элемент.
+- `IOrderedListProps` и `IOrderedListItemProps` остаются публичными интерфейсами
+  стандартных HTML-атрибутов; barrel-экспорты не удаляются.
+- Не заменяй проверку `start !== undefined` на проверку truthy: `start={0}` допустим.
+- Сохраняй связь `start - 1` с CSS-счётчиком пунктов и порядок `{...style, "--...": start - 1}`.
+  Имя runtime-переменной меняй разом в `OrderedList.tsx` и `OrderedList.module.less`:
+  оно видно в inline-стиле корневого `<ol>`.
+- Не убирай объявление runtime-переменной со значением 0 в классе `.orderedList`:
+  без него вложенный список унаследует сброс счётчика родителя.
+- `className` объединяется через `clsx`, остальные атрибуты пробрасываются на `<ol>`.
+  `data-tx` устанавливается из версии пакета после spread пользовательских атрибутов.
+- `displayName` списка — `"OrderedList"`, пункта — `"OrderedListItem"`.
+- Story exports `Default`, `WithLongContent` и `Start` определяют IDs визуальных тестов;
+  `Playground` из скриншот-тестов исключён.
 
-- React inline-style с CSS-переменной (`as keyof React.CSSProperties` cast — TS-хак).
-- `start - 1` потому что `counter-increment` срабатывает **до** рендера `::before`, поэтому нужно начать на 1 меньше.
-- Также пробрасывается **нативный `start` атрибут** на `<ol>` — для семантики (скринридеры, copy-paste).
+---
 
-### `OrderedListItem` — типография зашита
+## Accessibility
 
-```tsx
-<Text tag="li" size={ETextSize.B3}>
-```
+Используется семантическая разметка `<ol>` / `<li>`. Компонент не задаёт собственных
+ARIA-атрибутов, не управляет фокусом и не обрабатывает клавиатуру. При необходимости
+потребитель передаёт `aria-label` или `aria-labelledby` на список. Номер пункта
+рисуется через `::before`, а текст приходит через `children`.
 
-- Размер **`B3`** — изменение требует копирования компонента или создания новой `size`-prop'ы.
+---
 
-### `Object.assign` — `OrderedList.Item`
+## Связанные компоненты
 
-Стандартный pattern для compound.
+- `OrderedListItem` / `OrderedList.Item` — публичная обёртка над `Text` с `tag="li"`
+  и `ETextSize.B3`, добавляющая стили номера и интервал между пунктами. Это тривиальная
+  обёртка без отдельного AI.md.
+- `UnorderedListExtended` — альтернатива с составным JSX-API и произвольными маркерами.
+- `UnorderedList` — альтернатива с маркированными пунктами, заданными массивом `items`.
+- `Text` — типографика пункта списка; прямые props типографики не входят в
+  `IOrderedListItemProps`.
 
-### `data-tx` — версия пакета
+---
 
-На обоих корнях (`<ol>` и `<li>`).
+## Stories
 
----
+Основные истории: `stories/OrderedList/OrderedList.stories.tsx`
+Файлы примеров: `stories/OrderedList/examples/`
 
-## Инварианты
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивная настройка `start`. |
+| `Default` | `Default.tsx` | Список из трёх пунктов с нумерацией от 1. |
+| `WithLongContent` | `WithLongContent.tsx` | Перенос длинного текста пункта на вторую строку. |
+| `Start` | `Start.tsx` | Начало нумерации с 5, 0 и −2. |
 
-- **`<ol>` с `list-style: none`** — нумерация рисуется через CSS-counter (`::before` с `counter()`).
-- **`OrderedListItem` — `<li>` через `<Text tag="li" size=B3>`** — типография B3 не настраивается.
-- **`start - 1`** в CSS-переменной (counter-increment-механика). При смене на `counter-reset` без `-1` — начнётся со start+1.
-- **Gap = 8px** между items (`+ .orderedListItem`).
-- **`start` дублируется** в DOM (`<ol start>`) и CSS-переменной — оба источника правды (DOM — для семантики, CSS — для рендера).
-- **ForwardRef** на обоих компонентах.
-- **Compound — `OrderedList.Item`** через `Object.assign`.
-- **`--start-index-tx`** — публичное имя CSS-переменной; не переименовывать.
+`Default`, `WithLongContent` и `Start` участвуют в визуальных тестах на xs/xl. `Start` покрывает
+нестандартное начало нумерации без отдельной дублирующей `VisualTests` story.
 
 ---
 
-## Accessibility
+## История изменений
 
-- `<ol>` + `<li>` — нативная семантика списка → скринридеры читают «список из N элементов, элемент 1 из N».
-- `start` пробрасывается в DOM — скринридер читает корректные номера.
-- `list-style: none` отключает **нативные маркеры**, но семантика `<ol>` сохраняется (Safari/VoiceOver на старых версиях иногда теряют семантику с `list-style: none` — известный edge case).
-- `::before` content `"1."` — может быть прочитан в зависимости от reader (не на всех — спецификация неоднозначна).
+| Дата | Изменение |
+|---|---|
+| 2026-10-07 | Создан документ. Уточнена типизация CSS-счётчика и JSDoc существующих props; CSS-переменная `--start-index-tx` переименована в `--triplex-next-runtime-OrderedList-Root_CounterReset`; добавлены тесты `start`, объединения `style` и повторного рендера, stories `Playground` и `Start`. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-Нет собственных. Типография — `B3` от `Text`. Размер padding-left = 25px, gap = 8px — захардкожены в LESS (не переменные).
+### Default
 
----
+`stories/OrderedList/examples/Default.tsx`
 
-## Связанные компоненты
+```tsx
+import React from "react";
+import { OrderedList } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <div style={{ maxWidth: 200 }}>
+        <OrderedList>
+            <OrderedList.Item>List item text;</OrderedList.Item>
+            <OrderedList.Item>List item text;</OrderedList.Item>
+            <OrderedList.Item>List item text.</OrderedList.Item>
+        </OrderedList>
+    </div>
+);
+```
 
-- `UnorderedList` — маркированный аналог.
-- `Text` (Typography) — типография элементов.
-- `ETextSize.B3` — размер.
+### WithLongContent
 
----
+`stories/OrderedList/examples/WithLongContent.tsx`
 
-## Stories
+```tsx
+import React from "react";
+import { OrderedList } from "@sberbusiness/triplex-next";
+
+export const WithLongContent = () => (
+    <div style={{ maxWidth: 200 }}>
+        <OrderedList>
+            <OrderedList.Item>List item text;</OrderedList.Item>
+            <OrderedList.Item>List item text;</OrderedList.Item>
+            <OrderedList.Item>Extremely long list item that fits in two lines.</OrderedList.Item>
+        </OrderedList>
+    </div>
+);
+```
 
-`stories/OrderedList/OrderedList.stories.tsx`
-Примеры: `stories/OrderedList/examples/`
+### Start
 
----
+`stories/OrderedList/examples/Start.tsx`
 
-## История изменений
+```tsx
+import React from "react";
+import { OrderedList } from "@sberbusiness/triplex-next";
+
+const START_VALUES = [5, 0, -2];
+
+export const Start = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 24, flexWrap: "wrap" }}>
+        {START_VALUES.map((start) => (
+            <div key={start} style={{ width: 200, height: 112, flexShrink: 0 }}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>start={start}</div>
+                <OrderedList start={start}>
+                    <OrderedList.Item>List item text;</OrderedList.Item>
+                    <OrderedList.Item>List item text;</OrderedList.Item>
+                    <OrderedList.Item>List item text.</OrderedList.Item>
+                </OrderedList>
+            </div>
+        ))}
+    </div>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |

package/bundle/components/Overlay.md

@@ -184,8 +184,8 @@ unit-тестами (`toHaveBeenCalledTimes(1)`).
 - `OverlayMask` (`Overlay.Mask`) — кликабельный фон.
 - `OverlayPanel` (`Overlay.Panel`) — выезжающая панель.
 - `LightBox`, `TopOverlay` — построены поверх механики оверлея.
-- `DropdownMobile` — мобильный оверлей `Dropdown`, построен на `OverlayBase`. Своего AI.md
-  не имеет, описан в `Dropdown-ai.md`.
+- `Puller` — нижняя шторка (мобильные версии `Dropdown`, `Tooltip` и др.), построена на
+  `OverlayBase`. Описан в `Puller-ai.md`.
 - `ModalWindow` — готовое центрированное модальное окно с шапкой, телом и футером, если
   нужен не низкоуровневый оверлей. На `Overlay` не построен — это отвод в другой класс
   задач, поэтому в `related` не входит.
@@ -217,6 +217,7 @@ Visual baseline для `components-overlay--visual-tests` генерируетс
 | 2026-08-27 | `OverlayBase` вызывает `onOpen` при монтировании с `opened={true}` — раньше первый рендер гасил все колбэки, и оверлей, смонтированный открытым, не сообщал об этом потребителю (release notes 1.44.0). |
 | 2026-06-17 | Создан документ. `Overlay` переведён на `forwardRef` (ref → корневой `div`, аддитивно, release notes 1.34.0). Дедуплицирован флаг `closing` (единый источник — `OverlayBase`). Codestyle/JSDoc cleanup в 4 файлах. Добавлены 4 unit-тест-файла. Исправлен двойной вызов `onClosing`/`onOpening` за переход — теперь ровно один раз (закреплено `toHaveBeenCalledTimes(1)`). |
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`OverlayBase`, `OverlayMask`, `OverlayPanel`, `DropdownMobile`); из `related` убраны несимметричные имена (`ModalWindow`). Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
+| 2026-10-21 | Переход на `Puller` (TRIPLEX-961): связанный `DropdownMobile` теперь `Puller`. |
 
 ---
 

package/bundle/components/PageIndicators.md

@@ -0,0 +1,306 @@
+---
+component: PageIndicators
+category: Navigation
+related: []
+tokens:
+  - PageIndicators.Indicator_Inactive_BackgroundColor_Default
+  - PageIndicators.Indicator_Inactive_BackgroundColor_Hover
+  - PageIndicators.Indicator_Inactive_BackgroundColor_Pressed
+  - PageIndicators.Indicator_Inactive_BackgroundColor_Disabled
+  - PageIndicators.Indicator_Active_BackgroundColor_Default
+  - PageIndicators.Indicator_Active_BackgroundColor_Hover
+  - PageIndicators.Indicator_Active_BackgroundColor_Pressed
+  - PageIndicators.Indicator_Active_BackgroundColor_Disabled
+  - PageIndicators.Indicator_OutlineColor
+stories: stories/PageIndicators/PageIndicators.stories.tsx
+version: "1.0"
+---
+
+# PageIndicators
+
+## Назначение
+
+Controlled-ряд индикаторов страниц: показывает, какая страница из `count` активна,
+и позволяет переключиться кликом или с клавиатуры. Одновременно видимо окно из 5
+индикаторов: активный — длинный, остальные — короче, а крайние индикаторы окна
+уменьшаются, если за ними есть ещё страницы. Смена страницы анимируется.
+
+Используй когда: нужен компактный индикатор положения в наборе слайдов/страниц —
+карусель, галерея изображений, онбординг-шаги без подписей.
+
+Не используй когда: страниц много и пользователю нужен переход к конкретному
+номеру или выбор размера страницы — для этого `Pagination`. Не используй как
+индикатор прогресса процесса с подписями шагов — для этого `Stepper`.
+
+---
+
+## Варианты и props
+
+Своего состояния активной страницы компонент не держит — `activeIndex` и
+`onChange` всегда задаёт потребитель.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `count` | `number` | Количество страниц. При `count < 1` компонент ничего не рендерит |
+| `activeIndex` | `number` | Индекс активной страницы (с 0). Значение вне диапазона приводится к ближайшей странице, чтобы у ряда всегда был активный индикатор, доступный по Tab |
+| `onChange` | `(index: number) => void` | Выбор страницы кликом или с клавиатуры. С клавиатуры вызывается только при реальной смене индекса (на границе диапазона — нет) |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `orientation` | `EOrientation` | `HORIZONTAL` | `HORIZONTAL` (`'horizontal'`) / `VERTICAL` (`'vertical'`): направление ряда и набор клавиш-стрелок |
+| `indicatorProps` | `TPageIndicatorProps \| TPageIndicatorPropsFactory` | — | Свойства кнопок-индикаторов: объект для всех или функция от `{ index, page, selected }`. Через неё задают `aria-label`, `disabled`, `data-*` |
+| `...HTMLDivAttributes` | — | — | Пробрасываются на корневой `<div>`. Кроме `onChange` (переопределён под выбор страницы) |
+
+В `indicatorProps` компонент переопределяет `role`, `tabIndex`, `aria-selected`
+(и `aria-hidden` для индикаторов вне окна); `className` и `style` мерджатся с
+собственными. `onClick` из `indicatorProps` вызывается после `onChange`.
+
+---
+
+## Дизайн-токены
+
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/PageIndicators.ts`.
+
+```text
+PageIndicators.Indicator_Inactive_BackgroundColor_Default
+PageIndicators.Indicator_Inactive_BackgroundColor_Hover
+PageIndicators.Indicator_Inactive_BackgroundColor_Pressed
+PageIndicators.Indicator_Inactive_BackgroundColor_Disabled
+
+PageIndicators.Indicator_Active_BackgroundColor_Default
+PageIndicators.Indicator_Active_BackgroundColor_Hover
+PageIndicators.Indicator_Active_BackgroundColor_Pressed
+PageIndicators.Indicator_Active_BackgroundColor_Disabled
+
+PageIndicators.Indicator_OutlineColor
+```
+
+Runtime CSS-переменные (задаются компонентом через `style`, **не** дизайн-токены,
+не попадают в `DesignTokens`):
+
+```
+--triplex-next-runtime-PageIndicators-Root_Size
+--triplex-next-runtime-PageIndicators-Indicator_Scale
+--triplex-next-runtime-PageIndicators-Indicator_Translate
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** обязателен; target — корневой `<div role="tablist">`.
+- **Controlled-only.** Не добавлять внутреннее состояние активной страницы —
+  `Carousel.Indicators` и `ImageGalleryExtended.PageIndicators` управляют им сами.
+- **Геометрия окна** (5 видимых, размеры 24 / 16 / 8 px, зазор 8 px) — визуальный
+  контракт; изменение ломает скриншот-регрессию `Carousel` и галереи.
+- **Кэшированные колбэки индикаторов** (ref и click по индексу) стабильны между
+  рендерами; актуальные `onChange` / `indicatorProps` читаются из рефов. Не
+  замыкать их напрямую — иначе устаревшее замыкание после ререндера.
+- **Отступы** (`padding: 1px` + `margin: -1px`) оставляют место для focus outline
+  при `overflow: hidden`. Внешние отступы задаёт потребитель через `className`
+  (селектором большей специфичности).
+- **Публичный API** (`PageIndicators`, общий `EOrientation` и значения
+  `'horizontal'`/`'vertical'`, `IPageIndicatorsProps`, `TPageIndicatorProps`,
+  `TPageIndicatorPropsFactory`, форма аргумента фабрики `{ index, page, selected }`)
+  — breaking change при изменении.
+
+---
+
+## Accessibility
+
+- **Роли:** корень — `role="tablist"` с `aria-orientation`, индикаторы —
+  `<button role="tab">` с `aria-selected`.
+- **Roving tabindex:** в последовательности Tab только активный индикатор
+  (`tabIndex=0`), остальные — `tabIndex=-1`. Если активный отключён, Tab-stop
+  получает ближайший доступный в видимом окне; если там доступных нет, Tab-stop
+  у ряда нет (скрытые индикаторы недоступны и мыши).
+- **Клавиатура** на ряду: `→` / `←` (горизонтально) или `↓` / `↑` (вертикально) —
+  следующая/предыдущая страница без зацикливания; `Home` / `End` — первая/последняя.
+  Обработанные клавиши получают `preventDefault`; `onKeyDown` потребителя
+  вызывается всегда.
+- **Фокус следует за выбором:** если фокус внутри ряда, после смены `activeIndex`
+  он переносится на новый активный индикатор (в `requestAnimationFrame`).
+- **Индикаторы вне окна** помечены `aria-hidden="true"`.
+- **Отключённые индикаторы** (`disabled` через `indicatorProps`) пропускаются
+  клавиатурой: стрелки, `Home` и `End` ведут к ближайшему доступному.
+- **`aria-label` — обязанность потребителя:** компонент не хардкодит язык.
+  Подпись индикаторам задают через `indicatorProps` (например, `Страница N`), ряду —
+  `aria-label` на корне.
+
+---
+
+## Связанные компоненты
+
+- `Carousel` — `Carousel.Indicators` рендерит `PageIndicators`, беря `count`,
+  `activeIndex`, `onChange` и ориентацию из контекста карусели; в режиме
+  `ECarouselScrollMode.ITEM` ничего не рендерит. Карусель добавляет только
+  раскладочные отступы и мобильное позиционирование.
+- `ImageGalleryExtended` — часть `.PageIndicators` рендерит `PageIndicators` с
+  индикатором на каждое изображение; `aria-label` по умолчанию — `item.alt`.
+- `Pagination` — альтернатива для длинных списков с номерами страниц.
+
+---
+
+## Stories
+
+Основные истории: `stories/PageIndicators/PageIndicators.stories.tsx`
+Файлы примеров: `stories/PageIndicators/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `count` и `orientation` |
+| `Default` | `Default.tsx` | Базовый горизонтальный ряд из 5 страниц |
+| `Orientations` | `Orientations.tsx` | Горизонтальная и вертикальная ориентация |
+| `ManyPages` | `ManyPages.tsx` | 12 страниц: скользящее окно из 5 индикаторов |
+| `CustomIndicatorProps` | `CustomIndicatorProps.tsx` | Фабрика `indicatorProps`: `aria-label`, `aria-controls`, `data-*` и связь с `tabpanel` |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: фокус, окно в начале/середине/конце, disabled, вертикальная ориентация |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-07 | Создан документ: компонент вынесен из `Carousel.Indicators` и встроен в `ImageGalleryExtended` |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/PageIndicators/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { PageIndicators } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [activeIndex, setActiveIndex] = useState(0);
+
+    return (
+        <PageIndicators
+            count={5}
+            activeIndex={activeIndex}
+            onChange={setActiveIndex}
+            aria-label="Страницы"
+            indicatorProps={({ page }) => ({ "aria-label": `Страница ${page}` })}
+        />
+    );
+};
+```
+
+### Orientations
+
+`stories/PageIndicators/examples/Orientations.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { PageIndicators, EOrientation } from "@sberbusiness/triplex-next";
+
+interface IOrientationItemProps {
+    orientation: EOrientation;
+}
+
+const OrientationItem = ({ orientation }: IOrientationItemProps) => {
+    const [activeIndex, setActiveIndex] = useState(0);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{orientation.toUpperCase()}</div>
+            <PageIndicators
+                count={5}
+                activeIndex={activeIndex}
+                onChange={setActiveIndex}
+                orientation={orientation}
+                aria-label="Страницы"
+                indicatorProps={({ page }) => ({ "aria-label": `Страница ${page}` })}
+            />
+        </div>
+    );
+};
+
+const ORIENTATIONS = Object.values(EOrientation);
+
+export const Orientations = () => (
+    <div style={{ display: "flex", alignItems: "flex-start", gap: 32, flexWrap: "wrap" }}>
+        {ORIENTATIONS.map((orientation) => (
+            <OrientationItem key={orientation} orientation={orientation} />
+        ))}
+    </div>
+);
+```
+
+### ManyPages
+
+`stories/PageIndicators/examples/ManyPages.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { PageIndicators } from "@sberbusiness/triplex-next";
+
+/**
+ * Одновременно видно окно из 5 индикаторов. Если за окном есть ещё страницы,
+ * крайние индикаторы окна уменьшаются; при переключении окно сдвигается за активным.
+ */
+export const ManyPages = () => {
+    const [activeIndex, setActiveIndex] = useState(0);
+
+    return (
+        <PageIndicators
+            count={12}
+            activeIndex={activeIndex}
+            onChange={setActiveIndex}
+            aria-label="Страницы"
+            indicatorProps={({ page }) => ({ "aria-label": `Страница ${page}` })}
+        />
+    );
+};
+```
+
+### CustomIndicatorProps
+
+`stories/PageIndicators/examples/CustomIndicatorProps.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { PageIndicators, TPageIndicatorPropsFactory } from "@sberbusiness/triplex-next";
+
+const PAGES_COUNT = 5;
+
+/** Свойства каждого индикатора вычисляются из его состояния: индекса, номера страницы и активности. */
+const getIndicatorProps: TPageIndicatorPropsFactory = ({ index, page, selected }) => ({
+    id: `page-tab-${index}`,
+    "aria-label": `Страница ${page}`,
+    "aria-controls": "page-panel",
+    title: selected ? `Страница ${page} (текущая)` : `Страница ${page}`,
+    // data-атрибуты удобны для e2e-тестов и аналитики.
+    "data-page": page,
+    "data-selected": selected,
+});
+
+export const CustomIndicatorProps = () => {
+    const [activeIndex, setActiveIndex] = useState(0);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+            <PageIndicators
+                count={PAGES_COUNT}
+                activeIndex={activeIndex}
+                onChange={setActiveIndex}
+                aria-label="Страницы"
+                indicatorProps={getIndicatorProps}
+            />
+            <div id="page-panel" role="tabpanel" aria-labelledby={`page-tab-${activeIndex}`}>
+                Содержимое страницы {activeIndex + 1} из {PAGES_COUNT}
+            </div>
+        </div>
+    );
+};
+```
+