@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Card.md

@@ -0,0 +1,374 @@
+---
+component: Card
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Island, IslandWidget, CardContent, CardMedia]
+tokens:
+  - --triplex-next-Card-Static_General_Background
+  - --triplex-next-Card-Static_Secondary_Background
+  - --triplex-next-Card-Action_General_Background
+  - --triplex-next-Card-Action_General_Background_Hover
+  - --triplex-next-Card-Action_General_Background_Selected
+  - --triplex-next-Card-Action_General_Background_Selected_Hover
+  - --triplex-next-Card-Action_Secondary_Background
+  - --triplex-next-Card-Action_Secondary_Background_Hover
+  - --triplex-next-Card-Action_Secondary_Background_Selected
+  - --triplex-next-Card-Action_Secondary_Background_Selected_Hover
+  - --triplex-next-Card-Shadow_Default
+  - --triplex-next-Card-Shadow_Hover
+  - --triplex-next-Card-Shadow_Selected
+  - --triplex-next-Card-Shadow_Selected_Hover
+  - --triplex-next-Card-Shadow_Focus
+stories: stories/Cards/CardStatic.stories.tsx, stories/Cards/CardAction.stories.tsx
+version: "1.0"
+---
+
+# Card
+
+## Назначение
+
+Семейство карточек: прямоугольный контейнер со скруглением, фоном и
+опциональной медиа-областью. Папка экспортирует **два** независимых
+публичных компонента:
+
+- **`CardStatic`** — статическая карточка. Используется как визуальный
+  блок-"плитка" контента.
+- **`CardAction`** — интерактивная карточка: `tabIndex=0`, `role="button"`,
+  обработка `Space`/`Enter`, состояния hover/selected/focus, controlled/
+  uncontrolled выбор.
+
+Оба содержат `Content` (с `Header`/`Body`/`Footer`) и `Media` как
+compound-subcomponents.
+
+Используй когда:
+- **`CardStatic`** — нужна карточка-контейнер для блока информации (профиль,
+  продукт, сводка), на которую не нужно кликать.
+- **`CardAction`** — карточка действует как большая кнопка/выбор: выбор
+  варианта, открытие деталей, чекбокс-карточка.
+
+Не используй когда: нужен структурный блок страницы с сайдбаром (бери
+`Island`); нужен виджет дашборда со слотами (бери `IslandWidget`).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Card/
+├── CardStatic.tsx                      # React.FC + compound (Content, Media)
+├── CardAction.tsx                      # React.Component (class) + compound
+├── enums.ts                            # ECardContentPaddingSize, ECardRoundingSize, ECardTheme
+├── types.ts                            # ICardProps, ICardActionProps
+├── utils.ts                            # mapCardRoundingSizeToCssClass, mapCardThemeToCssClass
+├── index.ts                            # Barrel: CardStatic + CardAction + enums + types
+├── styles/
+│   ├── Card.module.less                # Общие стили .card + rounding + theme + content
+│   └── Action.module.less              # .action specific (cursor, shadow/hover/focus)
+├── components/
+│   ├── CardMedia.tsx                   # Медиа-блок (обычно <div> с background-image)
+│   └── CardContent/
+│       ├── CardContent.tsx             # + Body / Header / Footer compound
+│       └── components/
+│           ├── CardContentBody.tsx
+│           ├── CardContentHeader.tsx
+│           └── CardContentFooter.tsx
+└── __tests__/
+```
+
+Особенности:
+- **Два разных паттерна реализации**: `CardStatic` — функциональный FC,
+  `CardAction` — class-component. Обусловлено состоянием focus-source и
+  controlled/uncontrolled логикой. Не унифицировать без рефакторинга.
+- **`forwardRef` НЕТ ни на одном** (class + FC). Ref на class приходит
+  через внутренний `this.ref` (не форвардится наружу). **Это известный
+  debt** — в roadmap AI-Ready.
+- **`CardStatic` и `CardAction`** делят LESS-файл `Card.module.less`
+  (общие `.card`, `.roundingMD`, `.general` etc.), а `Action.module.less`
+  добавляет только action-специфику.
+- **`CardContent` с compound `Body`/`Header`/`Footer`** — не обязательны,
+  но дают стандартные отступы (header: margin-bottom 16px, footer: margin-top 16px).
+
+---
+
+## Варианты и props
+
+### `ICardProps extends React.HTMLAttributes<HTMLDivElement>` (CardStatic)
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `roundingSize` | `ECardRoundingSize` (`MD` / `SM`) | `MD` | Скругление: MD=16px, SM=8px. |
+| `theme` | `ECardTheme` (`GENERAL` / `SECONDARY`) | `GENERAL` | Тема фона (Static_General_Background / Static_Secondary_Background). |
+| `children` | `React.ReactNode` | — | Обычно `CardMedia` и/или `CardContent`. |
+| `className` | `string` | — | Доп. класс (`clsx` с базовыми). |
+| `...HTMLDivAttributes` | — | — | Все стандартные. |
+
+### `ICardActionProps extends ICardProps` (CardAction)
+
+Наследует `roundingSize`, `theme` + добавляет:
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `selected` | `boolean` | — | Controlled-состояние выбора. Если `undefined` → uncontrolled. |
+| `toggle` | `(selected: boolean) => void` | — | Controlled-хендлер. Вызывается при клике/клавиатуре в controlled-режиме. |
+| `onToggle` | `(selected: boolean) => void` | — | Uncontrolled-хендлер. Вызывается после изменения внутреннего state. |
+
+**Controlled определяется один раз в конструкторе:** `isControlled: this.props.selected !== undefined`. Переключать
+`selected` из `undefined` в `false` между рендерами — **не** превратит
+компонент в controlled, флаг остался `false`. Если нужен controlled —
+передай `selected` с самого начала.
+
+### `CardContent` / `CardContent.Body/Header/Footer` / `CardMedia`
+
+`CardContent`:
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `paddingSize` | `ECardContentPaddingSize` (`MD` / `SM`) | `MD` | Внутренний padding: MD=24px, SM=16px. |
+| `children` | — | — | Обычно `Header`/`Body`/`Footer` или свободный контент. |
+
+`CardContent.Body/Header/Footer` и `CardMedia` — тонкие div-обёртки без
+дополнительных props. У `CardContentHeader/Footer` фиксированные отступы
+(`margin-bottom: 16px` / `margin-top: 16px`) относительно Body.
+
+### Enums
+
+| Enum | Значения | Что делает |
+|---|---|---|
+| `ECardRoundingSize` | `MD = "md"`, `SM = "sm"` | Border-radius: 16px / 8px. |
+| `ECardTheme` | `GENERAL`, `SECONDARY` | Switch между Static_*/Action_* токенами. |
+| `ECardContentPaddingSize` | `MD = "md"`, `SM = "sm"` | Padding CardContent: 24px / 16px. |
+
+---
+
+## Ключевые особенности реализации
+
+### `CardAction` — class component с EFocusSource
+
+```ts
+public state = {
+    focusSource: EFocusSource.NONE,
+    isControlled: this.props.selected !== undefined,
+    isSelected: !!this.props.selected,
+};
+```
+
+`EFocusSource` из `src/enums/EFocusSource` различает KEYBOARD / MOUSE / NONE.
+Только `KEYBOARD`-фокус рендерит `.focusVisible` → видимая focus-рамка.
+Click мышью не показывает рамку (выглядит как "неподсвеченная" кнопка).
+Это соответствует нативному `:focus-visible`, но реализовано вручную для
+поддержки старых браузеров.
+
+### `handleKeyDown` — Space и Enter
+
+```ts
+if (isKey(event.keyCode, "SPACE")) {
+    event.preventDefault();       // важно: без preventDefault страница прокрутится
+    this.handleToggle();
+} else if (isKey(event.keyCode, "ENTER")) {
+    this.handleToggle();          // без preventDefault — Enter не прокручивает
+}
+```
+
+Не убирать `event.preventDefault()` для SPACE. Без него страница прокрутится
+на 1 экран при выборе карточки.
+
+### `componentDidUpdate` — синхронизация controlled-пропсы с onToggle
+
+```ts
+if (selected !== prevProps.selected) {
+    onToggle?.(!!selected);
+}
+```
+
+**Странный паттерн: `onToggle` вызывается и в controlled-режиме при
+внешнем изменении `selected`.** Это осознанный фичфикс — позволяет
+слушать все изменения единым хендлером. Не удалять (сломает consumer'ов,
+которые делают `onToggle={log}`).
+
+### `handleToggle` — две ветки
+
+```ts
+if (isControlled) {
+    toggle?.(!selected);
+} else {
+    this.setState(prev => ({isSelected: !prev.isSelected}), () => onToggle?.(!isSelected));
+}
+```
+
+Controlled → вызывает `toggle`. Uncontrolled → локальный setState + колбэк
+`onToggle`. **Внимание**: в `onToggle?.(!isSelected)` используется
+**захваченный** `isSelected` из destructure, не актуальный из setState
+callback'а. Это намеренно: даёт значение после переключения.
+
+### `isControlled: this.props.selected !== undefined` — фиксируется в initial state
+
+Значит, переключение режима на лету не поддерживается. Если нужно —
+передавай `selected={undefined}` с самого начала и потом управляй им.
+В остальном — выбирай один режим.
+
+### `CardStatic.Content / .Media` — присваивание свойствам FC
+
+```ts
+CardStatic.Content = CardContent;
+CardStatic.Media = CardMedia;
+CardStatic.displayName = "CardStatic";
+```
+
+Вместо `Object.assign` как в Badge — прямое присваивание. Эквивалентно.
+Type augmentation через `React.FC<ICardProps> & ICardStaticComposition`.
+TypeScript требует объявленного интерфейса композиции для FC — иначе
+`.Content` не типизируется.
+
+### `--radius` / `--padding` CSS-переменные
+
+`roundingMD/SM` меняют CSS-переменную `--radius` на root `.card`, которую
+подхватывают и `.card { border-radius: var(--radius) }`, и
+`::before { border-radius: var(--radius) }` в Action. Та же техника для
+`--padding` в `.cardContent`.
+
+**`--card-inner-shadow`** в CardAction создаёт внутреннюю тень (для
+selected / focus) через `::before` с `box-shadow` — чтобы не ломать
+`border-radius` + `overflow: hidden` на родителе.
+
+### `mapCardThemeToCssClass` / `mapCardRoundingSizeToCssClass`
+
+Плоские объекты (не функция `createSizeToClassNameMap`). Простые маппинги
+без TypeScript-валидации полноты. При добавлении нового enum-значения
+нужно обновлять явно — без подсказки от компилятора.
+
+### `role="button"` + `tabIndex={0}` на CardAction
+
+CardAction — `<div>` с ARIA-ролью "button". Потребитель может переопределить
+через `...attributes` (spread после role), но обычно не нужно. **Не
+оборачивать в `<button>`** — в контенте часто есть другие кнопки/ссылки,
+nested interactive — не валиден.
+
+---
+
+## Инварианты
+
+- **CardStatic — FC, CardAction — class** — не унифицировать без согласования.
+- **CardAction controlled/uncontrolled определяется один раз** — не менять
+  паттерн на динамическое определение.
+- **`componentDidUpdate` в CardAction вызывает `onToggle` при изменении
+  `selected`** — не удалять, консюмеры полагаются.
+- **`role="button"` + `tabIndex={0}` на CardAction** — не убирать. Это базовая
+  a11y.
+- **`event.preventDefault()` для SPACE в `handleKeyDown`** — не удалять
+  (прокрутка страницы).
+- **`displayName`** на каждом (CardStatic, CardAction, CardContent, CardMedia,
+  CardContentBody/Header/Footer) — для девтулзов.
+- **`data-tx={process.env.npm_package_version}`** на обоих root-обёртках
+  (CardStatic и CardAction) — не удалять.
+- **`overflow: hidden` на `.card`** — не убирать. Обеспечивает обрезку
+  media-изображения по скруглению.
+- **`::before` с `--card-inner-shadow`** в Action — не схлопывать в
+  box-shadow самого блока, иначе `overflow: hidden` скроет тень.
+- **`.cardContentHeader { margin-bottom: 16px }` / `.cardContentFooter {
+  margin-top: 16px }`** — фиксированные отступы, не токенизированы. При
+  дизайн-ревью могут быть пересмотрены.
+- **Нет `forwardRef`** — известный debt. Не добавлять точечно без
+  согласования (поменяет семантику ref для CardAction, где сейчас
+  `this.ref` используется в focus-логике).
+
+---
+
+## Accessibility
+
+- **`CardAction`**:
+  - `role="button"` + `tabIndex={0}` — валидная интерактивная роль.
+  - Клавиатура: `Enter` и `Space` triggering toggle. Space preventDefault'ится
+    от скролла.
+  - Focus-ring появляется **только** при клавиатурной навигации (EFocusSource)
+    — соответствует `:focus-visible`.
+  - `aria-pressed` / `aria-selected` — **компонент НЕ добавляет**. Если
+    CardAction работает как toggle-button, потребитель должен передать
+    `aria-pressed={selected}` (или `aria-selected` для списков). Без этого
+    screen reader не знает о состоянии выбора.
+- **`CardStatic`** — семантически нейтральный div. Если используется как
+  ссылка, потребитель оборачивает в `<a>` или добавляет `role="link"` +
+  `href`-подобное поведение.
+- **Nested interactive**: внутри CardAction могут быть ссылки/кнопки —
+  браузеры/screen reader могут повести себя неожиданно (клик по внутренней
+  кнопке триггерит и карту). В таких случаях используй `CardStatic` +
+  отдельную кнопку, либо `e.stopPropagation()` на вложенных элементах.
+
+---
+
+## Дизайн-токены
+
+**CardStatic:**
+```
+--triplex-next-Card-Static_General_Background      # theme=GENERAL
+--triplex-next-Card-Static_Secondary_Background    # theme=SECONDARY
+```
+
+**CardAction (theme=GENERAL):**
+```
+--triplex-next-Card-Action_General_Background
+--triplex-next-Card-Action_General_Background_Hover
+--triplex-next-Card-Action_General_Background_Selected
+--triplex-next-Card-Action_General_Background_Selected_Hover
+```
+
+**CardAction (theme=SECONDARY):**
+```
+--triplex-next-Card-Action_Secondary_Background
+--triplex-next-Card-Action_Secondary_Background_Hover
+--triplex-next-Card-Action_Secondary_Background_Selected
+--triplex-next-Card-Action_Secondary_Background_Selected_Hover
+```
+
+**Тени (только CardAction):**
+```
+--triplex-next-Card-Shadow_Default
+--triplex-next-Card-Shadow_Hover
+--triplex-next-Card-Shadow_Selected
+--triplex-next-Card-Shadow_Selected_Hover
+--triplex-next-Card-Shadow_Focus                # через --card-inner-shadow
+```
+
+**Размеры не токенизированы:** radius (16/8), padding (24/16),
+margin-header/footer (16) — жёстко в LESS. Кандидаты на размерные токены.
+
+---
+
+## Связанные компоненты
+
+- `Island` (`src/components/Island`) — крупный блок с заголовком/футером/
+  сайдбаром. Выше Card по иерархии страницы.
+- `IslandWidget` (`src/components/IslandWidget`) — виджет дашборда с
+  разметкой под дрегабл-сетку.
+- `CardContent`, `CardMedia` — subcomponents, доступны и как `CardStatic.Content`,
+  `CardAction.Content`, `CardStatic.Media`, `CardAction.Media`.
+- `EFocusSource` (`src/enums/EFocusSource`) — используется в Checkbox,
+  Radio, CardAction и др. для различения mouse/keyboard-фокуса.
+- `isKey` (`src/utils/keyboard`) — утилита проверки keyCode.
+
+---
+
+## Stories
+
+Две stories-файла (по одному на компонент):
+
+`stories/Cards/CardStatic.stories.tsx`
+Примеры: `stories/Cards/examples/CardStatic/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `roundingSize`, `theme`, `paddingSize` |
+| `Default` | `DefaultExample.tsx` | Базовое использование с Content |
+| `Themes` | `ThemesExample.tsx` | GENERAL vs SECONDARY |
+| `RoundingSizes` | `RoundingSizesExample.tsx` | MD vs SM скругление |
+| `PaddingSizes` | `PaddingSizesExample.tsx` | MD vs SM padding |
+
+`stories/Cards/CardAction.stories.tsx`
+Примеры: `stories/Cards/examples/CardAction/` (тот же набор + интерактив).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/CarouselExtended.md

@@ -0,0 +1,250 @@
+---
+component: CarouselExtended
+category: Navigation
+figma-node: ""
+figma-file: ""
+related: [TabsExtended, SliderExtended]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# CarouselExtended
+
+## Назначение
+
+Горизонтальная карусель с управляющими кнопками prev/next в виде render-функций.
+Скроллит children по горизонтали через `scrollSmoothHorizontally`
+(animated `scrollLeft` через requestAnimationFrame). Автоматически управляет
+состояниями кнопок: `disabled` на краях, `hidden` если контент помещается
+целиком.
+
+"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).
+
+---
+
+## Варианты и props
+
+### `ICarouselExtendedProps extends React.HTMLAttributes<HTMLDivElement>`
+
+**Обязательные:**
+
+| 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)`. |
+
+**Опциональные:**
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `React.ReactNode` | Контент карусели (чипы, карточки, любые inline-элементы). |
+| `className`, `style`, `id`, остальные HTML-атрибуты — передаются на **внешний** div-обёртку, НЕ на скроллируемый контейнер. |
+
+### `ICarouselExtendedButtonProvideProps extends React.ButtonHTMLAttributes<HTMLButtonElement>`
+
+Передаётся в render-функции кнопок:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `disabled` | `boolean` | true, если скролл достиг края (prev → start, next → end). |
+| `hidden` | `boolean` | true, если контент помещается целиком (`scrollWidth === clientWidth`). Обычно потребитель рендерит `null` или применяет `visibility: hidden`. |
+| `onClick` | `() => void` | Обработчик клика — вызывает `scrollSmoothHorizontally`. |
+
+---
+
+## Ключевые особенности реализации
+
+### `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. Не убирать ни один — каждый
+нужен для своего браузера.
+
+---
+
+## Инварианты
+
+- **`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.
+
+---
+
+## 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 из карусели выходит нормально.
+
+---
+
+## Дизайн-токены
+
+Нет — компонент полностью структурный. Цвета/размеры задаёт контент и
+внешние кнопки.
+
+---
+
+## Связанные компоненты
+
+- `TabsExtended` (`src/components/TabsExtended`) — часто использует
+  CarouselExtended внутри для скролла tab-row'а при переполнении.
+- `SliderExtended` (`src/components/SliderExtended`) — семейно названный
+  компонент, но про другое (range-slider, не карусель).
+- `scrollSmoothHorizontally` (`src/utils/scroll.ts`) — единственная
+  внутренняя зависимость, больше нигде не используется.
+
+---
+
+## Stories
+
+**Нет stories.** Это известный пробел (ROADMAP.md: Storybook ⬜). Компонент
+используется внутри TabsExtended и в потребительских приложениях без
+отдельной демонстрации.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |