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

package/bundle/components/CarouselExtended.md

@@ -1,11 +1,9 @@
 ---
 component: CarouselExtended
-category: Navigation
-figma-node: ""
-figma-file: ""
-related: [TabsExtended, SliderExtended]
+category: CarouselExtended
+related: [Stepper]
 tokens: []
-stories: ""
+stories: stories/CarouselExtended/CarouselExtended.stories.tsx
 version: "1.0"
 ---
 
@@ -13,233 +11,198 @@ version: "1.0"
 
 ## Назначение
 
-Горизонтальная карусель с управляющими кнопками prev/next в виде render-функций.
-Скроллит children по горизонтали через `scrollSmoothHorizontally`
-(animated `scrollLeft` через requestAnimationFrame). Автоматически управляет
-состояниями кнопок: `disabled` на краях, `hidden` если контент помещается
-целиком.
+Горизонтально прокручиваемая лента произвольного контента с кнопками прокрутки.
+Компонент владеет только прокруткой и состоянием кнопок: разметку кнопок, их
+внешний вид и позиционирование задаёт потребитель через рендер-функции
+`buttonPrev` и `buttonNext`.
 
-"Extended" в имени — маркер того, что внешний вид кнопок не фиксирован:
-потребитель через render-пропы `buttonPrev`/`buttonNext` сам решает, как
-их рендерить, получая состояние (`disabled`, `hidden`, `onClick`).
+Используй когда: контент выкладывается в один горизонтальный ряд, его ширина
+заранее неизвестна (шаги процесса, применённые фильтры, теги, набор периодов), и
+нужны кнопки прокрутки в оформлении конкретного продукта.
 
-Используй когда: нужен горизонтальный list контента, не помещающегося в
-ширину (табы, карточки, чипы) с кастомными кнопками навигации.
-Не используй когда: нужна пагинация страниц (бери `Pagination`); нужна
-вертикальная прокрутка (компонент только горизонтальный); нужна карусель
-с auto-play / слайд-переходами (компонент не делает слайдов, только скролл).
+Не используй когда:
 
----
-
-## Файловая структура
-
-```text
-src/components/CarouselExtended/
-├── CarouselExtended.tsx                    # React.forwardRef, hooks (useState/Effect/Callback/Ref)
-├── index.ts                                # Barrel
-└── styles/CarouselExtended.module.less     # .carouselExtended (flex + скрытый скроллбар)
-```
-
-Особенности:
-- **Нет stories** — компонент не демонстрируется в Storybook. Это известный
-  gap (в ROADMAP.md Storybook-колонка ⬜). Не создавать без общей задачи.
-- **Нет subcomponents / compound'а** — кнопки рендерит потребитель через
-  render-пропы.
-- **Нет дизайн-токенов** — компонент структурный, всё визуальное (цвет
-  кнопок, размеры) задаёт потребитель.
-- **Использует `lodash` (не `lodash-es`)** — исключение из общего правила.
-  Не менять на lodash-es без общего рефакторинга импортов (вероятно
-  исторически, до перехода на ESM).
+- Нужна слайдовая карусель с постраничной прокруткой, индикаторами, клавиатурой
+  и touch-жестами — для этого есть составной `Carousel`
+  (`src/components/Carousel/`) с `Viewport` / `Track` / `Item` / `Indicators`.
+- Нужна лента шагов процесса — возьми `Stepper`, он уже собран на
+  `CarouselExtended` и добавляет выравнивание по выбранному шагу.
+- Контент заведомо помещается в контейнер — обычного блока достаточно,
+  компонент не даст ничего, кроме скрытого скроллбара.
+- Прокрутка нужна по вертикали — компонент прокручивает только по горизонтали.
 
 ---
 
 ## Варианты и props
 
-### `ICarouselExtendedProps extends React.HTMLAttributes<HTMLDivElement>`
-
-**Обязательные:**
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `buttonPrev` | `(props: ICarouselExtendedButtonProvideProps) => React.ReactNode` | Render-функция кнопки "Назад". Получает `disabled`, `hidden`, `onClick`. Оборачивать в `React.Fragment` не нужно — возвращается ReactNode. |
-| `buttonNext` | `(props: ICarouselExtendedButtonProvideProps) => React.ReactNode` | Render-функция кнопки "Вперёд". |
-| `stepPrev` | `number` | Сколько пикселей прокрутить влево при клике на prev. Округляется через `Math.floor(-stepPrev)`. |
-| `stepNext` | `number` | Сколько пикселей прокрутить вправо при клике на next. Округляется через `Math.ceil(stepNext)`. |
+| `buttonPrev` | `(props: ICarouselExtendedButtonProvideProps) => React.ReactNode` | Рендер-функция кнопки «Назад». Вызывается на каждом рендере, результат ставится перед лентой |
+| `buttonNext` | `(props: ICarouselExtendedButtonProvideProps) => React.ReactNode` | Рендер-функция кнопки «Вперёд». Результат ставится после ленты |
+| `stepPrev` | `number` | Величина прокрутки в px за один клик по кнопке «Назад» |
+| `stepNext` | `number` | Величина прокрутки в px за один клик по кнопке «Вперёд» |
 
-**Опциональные:**
+`children` и остальные атрибуты `React.HTMLAttributes<HTMLDivElement>`
+(`className`, `style`, `data-*`, обработчики) — опциональны и уходят на корневой
+элемент.
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `children` | `React.ReactNode` | Контент карусели (чипы, карточки, любые inline-элементы). |
-| `className`, `style`, `id`, остальные HTML-атрибуты — передаются на **внешний** div-обёртку, НЕ на скроллируемый контейнер. |
+### Что получают рендер-функции кнопок
 
-### `ICarouselExtendedButtonProvideProps extends React.ButtonHTMLAttributes<HTMLButtonElement>`
+`ICarouselExtendedButtonProvideProps` — это `React.ButtonHTMLAttributes`, но
+фактически компонент передаёт ровно три поля:
 
-Передаётся в render-функции кнопок:
-
-| Поле | Тип | Описание |
-|---|---|---|
-| `disabled` | `boolean` | true, если скролл достиг края (prev → start, next → end). |
-| `hidden` | `boolean` | true, если контент помещается целиком (`scrollWidth === clientWidth`). Обычно потребитель рендерит `null` или применяет `visibility: hidden`. |
-| `onClick` | `() => void` | Обработчик клика — вызывает `scrollSmoothHorizontally`. |
+| Поле | Когда выставляется |
+|---|---|
+| `disabled` | Достигнут соответствующий край ленты. Для `buttonPrev` — `scrollLeft <= 0`, для `buttonNext` — правый край |
+| `hidden` | Прокрутка не нужна: `scrollWidth === clientWidth` |
+| `onClick` | Всегда. Запускает анимированную прокрутку на `stepPrev` / `stepNext` |
+
+### Особенности поведения
+
+- **`hidden` — это подсказка, а не автоматическое скрытие.** Компонент всегда
+  вызывает обе рендер-функции; решение принимает потребитель. Обычно `hidden`
+  деструктурируют и возвращают `null` (так делают `Stepper` и все примеры).
+  Если прокинуть `hidden` дальше на нативную кнопку, сработает HTML-атрибут
+  `hidden` и кнопка скроется через `display: none` — в вёрстке на flex/grid это
+  даёт другой результат, чем отсутствие узла.
+- **Начальное состояние до первого измерения:** `hidden: true`,
+  `prevDisabled: true`, `nextDisabled: false`. Render-функции вызываются уже на
+  первом рендере, поэтому наличие кнопок в DOM определяет потребитель: при
+  рекомендованном `hidden → null` на первом кадре их нет. Реальное состояние
+  приходит после первого `useEffect`.
+- **Когда пересчитывается состояние кнопок:** монтирование, смена `children`,
+  `resize` окна, `scroll` документа и прокрутка самой ленты (`onScroll`).
+  `ResizeObserver` не используется — изменение ширины контейнера **без** ресайза
+  окна (раскрытие соседней панели, смена лейаута) само по себе пересчёта не
+  вызывает. Состояние также обновится при любой прокрутке ленты.
+- **Прокрутка анимирована** утилитой `scrollSmoothHorizontally`: 24 кадра через
+  `requestAnimationFrame`. Клик во время анимации не отменяет предыдущую —
+  анимации складываются.
+- **Дробный шаг округляется вверх по модулю:** `Math.floor(-stepPrev)` и
+  `Math.ceil(stepNext)`. Шаг `200.2` даёт прокрутку на `201` px в обе стороны.
+- **Скроллбар скрыт стилями** (`scrollbar-width: none`, `-ms-overflow-style`,
+  `::-webkit-scrollbar`). Прокрутка колесом, тачпадом и тач-жестом работает
+  штатно, но визуального индикатора наличия скрытого контента нет — единственная
+  подсказка для пользователя — кнопки.
+- **Внутренний контейнер ленты не настраивается снаружи:** `className` и `style`
+  уходят на корневой элемент, у прокручиваемого `div` только собственный класс.
+  Поэтому `gap` между элементами задать нельзя — отступы вешаются на сами
+  элементы (`marginRight` в примерах). Элементы ленты — flex-элементы: чтобы они
+  не сжимались и лента действительно прокручивалась, им нужен `flex: 0 0 auto`.
+- **`hidden` считается по `clientWidth`, а `nextDisabled` — по `offsetWidth`.**
+  Значения расходятся, если у ленты появятся границы, padding-бокс с рамкой или
+  горизонтальный скроллбар занимает место. Сейчас стили этого не допускают.
 
 ---
 
-## Ключевые особенности реализации
-
-### `forwardRef` с компонентным разделением refs
-
-```ts
-const carouselRef = useRef<HTMLDivElement | null>(null);
-const setRef = (instance: HTMLDivElement | null) => {
-    carouselRef.current = instance;
-    if (typeof ref === "function") ref(instance);
-    else if (ref) ref.current = instance;
-};
-```
-
-`ref`, прокинутый через `forwardRef`, указывает на **скроллируемый внутренний**
-div, НЕ на внешнюю обёртку (на которую идут htmlDivAttributes). Это
-осознанное решение: ref нужен для программного управления скроллом.
-**Не путать с внешней div-обёрткой** — она без ref и, например, `className`
-потребителя идёт на неё.
-
-### `checkControls` вычисляет `hidden`, `nextDisabled`, `prevDisabled`
-
-```ts
-hidden: carousel.scrollWidth == carousel.clientWidth,
-nextDisabled: Math.round(carousel.scrollLeft) + carousel.offsetWidth >= carousel.scrollWidth,
-prevDisabled: Math.round(carousel.scrollLeft) <= 0,
-```
-
-`Math.round` на `scrollLeft` — защита от subpixel-значений (при zoom или
-DPR ≠ 1 значение может быть дробным, что ломает strict-сравнение).
-`offsetWidth` vs `clientWidth` — намеренно. `offsetWidth` включает границы
-(у компонента их нет → эквивалентно), а `scrollWidth` и `clientWidth` могут
-разойтись на 1px при dense rendering.
-
-### `isEqual` предотвращает лишние ререндеры
-
-```ts
-if (isEqual(newState, controlsState) == false) {
-    setControlsState(newState);
-}
-```
-
-Без этой проверки каждый `scroll`-event триггерил бы `setState` → ререндер
-children. Глубокое сравнение из lodash: объект маленький (3 булевых поля),
-но на hot-path.
-
-### Слушает и window.resize, и document.scroll
-
-```ts
-window.addEventListener("resize", checkControls);
-document.addEventListener("scroll", checkControls);
-```
-
-**`document.scroll`** — не очевидное решение. Нужно, потому что при скролле
-самой страницы могут измениться размеры (например, если карусель внутри
-sticky-элемента, его реальная ширина меняется). Не убирать.
-
-Плюс `onScroll` на самом carousel-div'е — для скролла внутри карусели.
-
-### `scrollSmoothHorizontally` с `requestAnimationFrame`
-
-`src/utils/scroll.ts` реализует плавный скролл через рекурсивный
-`requestAnimationFrame` (24 кадра по умолчанию), уменьшая amount каждый
-кадр. **Не использует** `scrollTo({behavior: "smooth"})` — вероятно для
-поддержки старых браузеров (IE, старых Edge) или для единообразия скорости
-анимации.
-
-### `useEffect(checkControls, [children, checkControls])`
-
-Перевычисляет состояние кнопок, когда меняются children. Без этого при
-динамическом добавлении/удалении карточек кнопки могли бы остаться в
-неправильном состоянии.
-
-### `// eslint-disable-next-line react-hooks/refs`
-
-Два места с disable — потому что `react-hooks/refs` правило не понимает
-render-пропы (думает, что ref утекает). Не удалять, правило тут ложно
-срабатывает.
-
-### Скрытый скроллбар в LESS
-
-```less
-scrollbar-width: none;     // Firefox
--ms-overflow-style: none;  // IE + Edge
-&::-webkit-scrollbar { display: none; }  // Chrome/Safari
-```
+## Дизайн-токены
 
-Три вендор-префикса для trimming scrollbar. Не убирать ни один — каждый
-нужен для своего браузера.
+Собственных CSS-переменных у компонента нет: `CarouselExtended.module.less`
+задаёт только раскладку прокручиваемой ленты (`display: flex`,
+`position: relative`, `overflow-y: hidden` — из-за чего `overflow-x` вычисляется
+в `auto`) и скрывает скроллбар во всех браузерных движках. Цвета и размеры
+приходят из контента и из кнопок, которые рендерит потребитель.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef` на скроллируемый внутренний div** (не внешний) — не менять.
-  Семантика ref = "скроллируемая область".
-- **`buttonPrev` / `buttonNext` — render-пропы, не элементы** — сохранять
-  сигнатуру `(props) => ReactNode`.
-- **`stepPrev` / `stepNext` — обязательные числа** — нет default'а,
-  потребитель должен осознанно выбрать величину.
-- **`Math.floor(-stepPrev)` и `Math.ceil(stepNext)`** — асимметричное
-  округление для симметричного покрытия при не-целых step'ах. Не менять
-  без проверки на эдж-кейсах.
-- **`window.resize` + `document.scroll` + `onScroll`** — три источника
-  триггера `checkControls`. Не удалять никакой, каждый покрывает свой
-  сценарий.
-- **`isEqual` из lodash** — не удалять, предотвращает ререндеры детей.
-- **Скрытие скроллбара** (три правила) — не удалять, дизайн-контракт.
-- **`htmlDivAttributes` на внешней обёртке, не на скроллируемом div** —
-  если поменять, className и event handlers потребителя окажутся на
-  скроллируемом контейнере, где могут конфликтовать с onScroll.
+- **`forwardRef` указывает на прокручиваемый контейнер, а не на корневой
+  элемент.** Это неочевидно и является публичным контрактом: `Stepper` читает по
+  этому ref `scrollLeft`, `getBoundingClientRect` и напрямую прокручивает ленту.
+  Переносить ref на корневой `div` нельзя.
+  Внутренний ref-колбэк мемоизирован по `ref`, поэтому от повторного отцепления и
+  прицепления узла избавлен только потребитель со стабильным ref (объектный или
+  мемоизированный колбэк). Инлайновый `ref={(node) => …}` пересоздаётся сам, и
+  React отцепляет узел на каждом рендере — это ограничение React, а не компонента.
+- **`className`, `style` и `...rest` уходят на корневой элемент** — именно на нём
+  потребитель строит раскладку (`display: flex`, `position: relative` для
+  наложенных кнопок). Не переносить на ленту.
+- **Порядок узлов в DOM:** `buttonPrev` → лента → `buttonNext`. Потребители
+  позиционируют кнопки относительно ленты (`Stepper` — абсолютно поверх краёв),
+  поэтому вставка дополнительных обёрток ломает их вёрстку.
+- **Имена и типы публичных сущностей** — `CarouselExtended`,
+  `ICarouselExtendedProps`, `ICarouselExtendedButtonProvideProps`, а также имена
+  props `buttonPrev` / `buttonNext` / `stepPrev` / `stepNext` — часть публичного
+  API. `ICarouselExtendedButtonProvideProps` выглядит опечаткой («Provide» вместо
+  «Provided»), но переименование — breaking change и делается только отдельным
+  решением с записью в release notes.
+- **`buttonPrev` и `buttonNext` — обязательные рендер-функции**, а не
+  `React.ReactNode`. Они вызываются во время рендера, поэтому не должны содержать
+  side-эффектов и собственных хуков.
+- **`displayName`** равен `"CarouselExtended"`.
+- **Класс `carouselExtended`** — единственный якорь прокручиваемого контейнера,
+  на него опираются unit-тесты.
+- Реализация остаётся React 17-совместимой (без `useId`,
+  `useSyncExternalStore` и прочих React 18-only API): код синхронизируется
+  в `release-0`.
 
 ---
 
 ## Accessibility
 
-- **Нет ARIA-ролей по умолчанию** — карусель как контейнер семантически
-  нейтральна. Если содержимое — таблы/карточки, они сами декларируют
-  роли.
-- **Клавиатурная навигация внутри** — задача содержимого (например, tab'ы
-  внутри имеют свою клавиатуру). CarouselExtended не перехватывает arrow
-  keys.
-- **Кнопки `hidden`** — когда контент помещается, потребитель решает: скрыть
-  через `null` (лучше для a11y — кнопки не в tab-order) или через
-  `hidden`/`visibility: hidden`. Hidden HTML-атрибут приходит в render-prop,
-  и если потребитель просто спредит его — браузер сам уберёт из tab-order.
-- **Screen reader и скролл** — при использовании в табах/навигации
-  потребитель может обернуть в `role="tablist"` и озвучивать позицию
-  через `aria-live`. Компонент сам этого не делает.
-- **Focus trap** — компонент НЕ делает trap. Tab из карусели выходит нормально.
-
----
-
-## Дизайн-токены
-
-Нет — компонент полностью структурный. Цвета/размеры задаёт контент и
-внешние кнопки.
+- Компонент не добавляет ролей и aria-атрибутов: ни корневой элемент, ни лента не
+  интерактивны и прозрачны для accessibility-дерева.
+- **`aria-label` кнопок — обязанность потребителя.** Компонент не хардкодит текст,
+  библиотека мультиязычная. В примерах кнопки подписаны
+  `aria-label="Прокрутить назад"` / `"Прокрутить вперёд"`.
+- `disabled` приходит в рендер-функцию: если прокинуть его на нативную `<button>`
+  (как делают `ButtonIcon` и примеры), кнопка на краю ленты корректно выпадает из
+  порядка табуляции и не читается как активная.
+- Кнопки — вспомогательная навигация, а не единственный способ добраться до
+  контента: лента прокручивается колесом, тачпадом и тач-жестом. Для
+  клавиатурной прокрутки самой ленты контейнер должен попасть в фокус — своего
+  `tabIndex` у него нет. Если контент внутри некликабельный (текст, теги без
+  обработчиков), добавь фокусируемую обёртку на стороне потребителя.
+- Прокрутка кнопкой не переносит фокус и не меняет DOM-порядок — контент,
+  уехавший за край, остаётся доступным скринридеру и табуляции.
+- `Stepper` дополнительно ставит кнопкам `tabIndex={-1}`: там прокрутка
+  дублируется выбором шага, и кнопки намеренно исключены из табуляции. Это
+  решение потребителя, а не поведение `CarouselExtended`.
 
 ---
 
 ## Связанные компоненты
 
-- `TabsExtended` (`src/components/TabsExtended`) — часто использует
-  CarouselExtended внутри для скролла tab-row'а при переполнении.
-- `SliderExtended` (`src/components/SliderExtended`) — семейно названный
-  компонент, но про другое (range-slider, не карусель).
-- `scrollSmoothHorizontally` (`src/utils/scroll.ts`) — единственная
-  внутренняя зависимость, больше нигде не используется.
+- `Stepper` (`src/components/Stepper/`) — единственный потребитель внутри
+  библиотеки и единственное место, которое опирается на хрупкую деталь: ref
+  указывает на прокручиваемую ленту. `Stepper` передаёт объектный ref, считает
+  шаги прокрутки через собственный `ResizeObserver` и сам выравнивает выбранный
+  шаг, меняя `scrollLeft`. Любое изменение ref-таргета или порядка узлов сломает
+  его в первую очередь.
+- `Carousel` (`src/components/Carousel/`) — современная слайдовая карусель со
+  своим составным API (`Carousel.Viewport`, `Carousel.Track`, `Carousel.Item`,
+  `Carousel.Indicators`, `Carousel.PrevButton` / `NextButton`), клавиатурой и
+  touch-жестами. Решает соседнюю задачу: там прокрутка постраничная или по
+  элементам, здесь — свободная лента произвольного контента. В таблице
+  `docs/ai/ROADMAP.md` пока нет, поэтому в `related` не указан.
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — то, что обычно
+  возвращают рендер-функции кнопок: он принимает `disabled` и `onClick` без
+  дополнительной обвязки. Компонент его не импортирует, выбор кнопки за
+  потребителем.
+- `scrollSmoothHorizontally` (`src/utils/scroll.ts`) — публичная утилита, на
+  которой построена анимация прокрутки. Тот же хелпер использует `Stepper`.
 
 ---
 
 ## Stories
 
-**Нет stories.** Это известный пробел (ROADMAP.md: Storybook ⬜). Компонент
-используется внутри TabsExtended и в потребительских приложениях без
-отдельной демонстрации.
+Основные истории: `stories/CarouselExtended/CarouselExtended.stories.tsx`
+Файлы примеров: `stories/CarouselExtended/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный подбор `stepPrev` / `stepNext`, количества элементов и ширины ленты |
+| `Default` | `Default.tsx` | Лента шире видимой области: кнопки видны, «Назад» заблокирована в начальном положении |
+| `WithShortContent` | `WithShortContent.tsx` | Контент помещается целиком: в рендер-функции приходит `hidden`, кнопки не рендерятся |
+| `Example: лента применённых фильтров` | `Example.tsx` | Production-like композиция с `Tag`: удаление фильтра меняет `children` и пересчитывает состояние кнопок |
+| `VisualTests` | `VisualTests.tsx` | Состояния, недостижимые без взаимодействия: лента, прокрученная в середину (активны обе кнопки) и до конца (кнопка «Вперёд» заблокирована) |
+
+`Playground` исключён из скриншот-тестов. Остальные stories снимаются на
+viewport'ах `xs` и `xl`; ширина ленты зафиксирована в px, поэтому кадры на обоих
+viewport'ах отличаются только окружением.
 
 ---
 
@@ -247,4 +210,202 @@ scrollbar-width: none;     // Firefox
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-13 | Создан документ. AI-рефакторинг (TRI-20): пересчёт состояния кнопок переведён на функциональный `setState` (слушатели `resize` / `scroll` больше не переподписываются на каждое изменение состояния), ref-колбэк стабилизирован, убраны non-null assertion'ы и устаревшие `eslint-disable`, импорт `isEqual` переведён с `lodash` на `lodash-es`, дополнен JSDoc props и компонента. Добавлены unit-тесты (20 кейсов) и stories в modern pattern. Публичный API не изменён: props, интерфейсы, barrel-экспорты, `forwardRef` на прокручиваемый контейнер и итоговая разметка — прежние. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/CarouselExtended/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { CaretleftStrokeSrvIcon24, CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { ButtonIcon, CarouselExtended, ICarouselExtendedButtonProvideProps } from "@sberbusiness/triplex-next";
+
+const MONTHS = [
+    "Январь",
+    "Февраль",
+    "Март",
+    "Апрель",
+    "Май",
+    "Июнь",
+    "Июль",
+    "Август",
+    "Сентябрь",
+    "Октябрь",
+    "Ноябрь",
+    "Декабрь",
+];
+
+/** Величина прокрутки за один клик по кнопке. */
+const SCROLL_STEP = 200;
+
+/** Пока прокрутка не нужна, компонент передаёт hidden: кнопка не рендерится. */
+const renderPrevButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить назад" {...buttonProps}>
+            <CaretleftStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+const renderNextButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить вперёд" {...buttonProps}>
+            <CaretrightStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+export const Default = () => (
+    <CarouselExtended
+        style={{ display: "flex", alignItems: "center", width: "480px" }}
+        buttonPrev={renderPrevButton}
+        buttonNext={renderNextButton}
+        stepPrev={SCROLL_STEP}
+        stepNext={SCROLL_STEP}
+    >
+        {MONTHS.map((month) => (
+            <div
+                key={month}
+                style={{
+                    flex: "0 0 auto",
+                    marginRight: "8px",
+                    padding: "8px 16px",
+                    border: "1px solid rgb(200, 202, 205)",
+                    borderRadius: "8px",
+                }}
+            >
+                {month}
+            </div>
+        ))}
+    </CarouselExtended>
+);
+```
+
+### WithShortContent
+
+`stories/CarouselExtended/examples/WithShortContent.tsx`
+
+```tsx
+import React from "react";
+import { CaretleftStrokeSrvIcon24, CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { ButtonIcon, CarouselExtended, ICarouselExtendedButtonProvideProps } from "@sberbusiness/triplex-next";
+
+const MONTHS = ["Январь", "Февраль", "Март"];
+
+/** Величина прокрутки за один клик по кнопке. */
+const SCROLL_STEP = 200;
+
+/** Контент помещается в ленту целиком, поэтому компонент передаёт hidden и кнопки не рендерятся. */
+const renderPrevButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить назад" {...buttonProps}>
+            <CaretleftStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+const renderNextButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить вперёд" {...buttonProps}>
+            <CaretrightStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+export const WithShortContent = () => (
+    <CarouselExtended
+        style={{ display: "flex", alignItems: "center", width: "480px" }}
+        buttonPrev={renderPrevButton}
+        buttonNext={renderNextButton}
+        stepPrev={SCROLL_STEP}
+        stepNext={SCROLL_STEP}
+    >
+        {MONTHS.map((month) => (
+            <div
+                key={month}
+                style={{
+                    flex: "0 0 auto",
+                    marginRight: "8px",
+                    padding: "8px 16px",
+                    border: "1px solid rgb(200, 202, 205)",
+                    borderRadius: "8px",
+                }}
+            >
+                {month}
+            </div>
+        ))}
+    </CarouselExtended>
+);
+```
+
+### Example: лента применённых фильтров
+
+`stories/CarouselExtended/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { CaretleftStrokeSrvIcon24, CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import {
+    ButtonIcon,
+    CarouselExtended,
+    EComponentSize,
+    ICarouselExtendedButtonProvideProps,
+    Tag,
+} from "@sberbusiness/triplex-next";
+
+const INITIAL_FILTERS = [
+    { id: "period", label: "Период: 01.01.2026 — 31.03.2026" },
+    { id: "account", label: "Счёт: 40702810000000000001" },
+    { id: "counterparty", label: "Контрагент: ООО «Ромашка»" },
+    { id: "amount", label: "Сумма: от 10 000 ₽" },
+    { id: "status", label: "Статус: исполнено" },
+    { id: "currency", label: "Валюта: RUB" },
+];
+
+/** Величина прокрутки за один клик по кнопке. */
+const SCROLL_STEP = 200;
+
+const renderPrevButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить назад" {...buttonProps}>
+            <CaretleftStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+const renderNextButton = ({ hidden, ...buttonProps }: ICarouselExtendedButtonProvideProps) =>
+    hidden ? null : (
+        <ButtonIcon aria-label="Прокрутить вперёд" {...buttonProps}>
+            <CaretrightStrokeSrvIcon24 paletteIndex={5} />
+        </ButtonIcon>
+    );
+
+export const Example = () => {
+    const [filters, setFilters] = useState(INITIAL_FILTERS);
+
+    const handleRemove = (id: string) => setFilters((prevFilters) => prevFilters.filter((filter) => filter.id !== id));
+
+    return (
+        <CarouselExtended
+            style={{ display: "flex", alignItems: "center", width: "480px" }}
+            buttonPrev={renderPrevButton}
+            buttonNext={renderNextButton}
+            stepPrev={SCROLL_STEP}
+            stepNext={SCROLL_STEP}
+        >
+            {filters.map(({ id, label }) => (
+                <Tag
+                    key={id}
+                    id={id}
+                    size={EComponentSize.MD}
+                    style={{ flex: "0 0 auto", marginRight: "8px" }}
+                    onRemove={handleRemove}
+                >
+                    {label}
+                </Tag>
+            ))}
+        </CarouselExtended>
+    );
+};
+```
+