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

package/bundle/components/CarouselViewport.md

@@ -0,0 +1,631 @@
+---
+component: CarouselViewport
+category: Carousel
+related: [Carousel]
+tokens: []
+stories: stories/Carousel/Carousel.stories.tsx
+version: "1.0"
+---
+
+# CarouselViewport
+
+## Назначение
+
+Область просмотра составного `Carousel`: обрезает ленту по своим границам,
+применяет отступы родителя и обрабатывает touch-жесты. Передаёт свой DOM-узел
+в контекст, чтобы `Carousel` измерял доступный размер и рассчитывал прокрутку.
+
+Используй внутри `Carousel`, оборачивая одну `Carousel.Track` со слайдами.
+Самостоятельной прокрутки и геометрии вне родителя нет; для свободно
+прокручиваемой ленты рассмотри `CarouselExtended`.
+
+Публичное обращение — `Carousel.Viewport` через
+`import { Carousel } from "@sberbusiness/triplex-next"`.
+Именованного экспорта `CarouselViewport` из пакета нет;
+`ICarouselViewportProps` экспортируется из публичного barrel семейства.
+
+```tsx
+import React from "react";
+import { Carousel } from "@sberbusiness/triplex-next";
+
+export const CardsCarousel = () => (
+    <Carousel viewportPadding={[8, 16]} style={{ width: 400, height: 180 }}>
+        <Carousel.Viewport>
+            <Carousel.Track>
+                {["Первая карточка", "Вторая карточка", "Третья карточка"].map((text, index) => (
+                    <Carousel.Item key={text} index={index} style={{ width: 240, height: 164 }}>
+                        {text}
+                    </Carousel.Item>
+                ))}
+            </Carousel.Track>
+            <Carousel.PrevButton aria-label="Предыдущая карточка" />
+            <Carousel.NextButton aria-label="Следующая карточка" />
+        </Carousel.Viewport>
+    </Carousel>
+);
+```
+
+Кнопки навигации внутри области появляются при наведении на неё.
+Индикаторы страниц размещай рядом с `Viewport`, чтобы они не попадали под
+`overflow: hidden`.
+
+---
+
+## Варианты и props
+
+Обязательных props и собственных вариантов оформления нет.
+`ICarouselViewportProps` наследует HTML-атрибуты `<div>`.
+
+| Prop | Назначение и ограничения |
+|---|---|
+| `children` | Лента `Carousel.Track` со слайдами и необязательные кнопки навигации |
+| `className` | Дополняет внутренний класс `viewPort` |
+| `style` | Передаётся на корневой `<div>`; приоритет runtime-переменной — см. «Дизайн-токены» |
+| `onTouchStart` | Вызывается после начала жеста, поэтому `preventDefault` в callback его не отменяет. При пустом `targetTouches` жест не начинается |
+| `onTouchMove`, `onTouchEnd`, `onTouchCancel` и остальные HTML-обработчики | Передаются на `<div>`. Встроенные move/end/cancel слушают `window` |
+| `aria-*`, `data-*`, `role`, `tabIndex` и остальные HTML-атрибуты | Передаются на корневой элемент; семантику и доступное имя задаёт потребитель |
+| `ref` | Внешний callback- или object-ref объединяется с `viewportRef` контекста и указывает на тот же `HTMLDivElement` |
+
+`orientation`, `viewportPadding` и `scrollMode` задаются на родительском
+`Carousel`, а не на `Viewport`. Не подменяй `viewportPadding` через CSS:
+измерения родителя должны соответствовать оформлению области.
+
+Корневой `<div>` имеет `width: 100%`, `height: 100%`, `box-sizing: border-box`
+и `overflow: hidden`. Ограничь размер композиции; для вертикальной карусели
+нужна ограниченная высота.
+
+### Touch-жесты
+
+- Учитывается первое касание из `targetTouches`; `touchmove` — с
+  `{ passive: false }`, пока жест не отдан прокрутке страницы.
+- Ось выбирается, когда смещение по любой оси стало **больше 5 px**
+  (`AXIS_LOCK_THRESHOLD`). Если поперечное смещение больше основного, жест
+  до конца отдаётся прокрутке страницы: без `preventDefault`, сдвига и
+  навигации. При равенстве выигрывает ось карусели. До выбора оси лента
+  не сдвигается, а `touchmove` не отменяется, чтобы браузер мог начать
+  прокрутку страницы. CSS-переход ленты отключается только после выбора
+  оси карусели, поэтому тап или прокрутка страницы не обрывают анимацию
+  перехода.
+- За границей ленты смещение уменьшается втрое (rubber-band,
+  `RUBBER_BAND_RESISTANCE`).
+- На `touchend` смещение вдоль оси **больше 50 px** (`SWIPE_THRESHOLD`)
+  вызывает `prevSlide`, меньше `-50 px` — `nextSlide`; ровно ±50 px не
+  переключает. Шаг перехода определяет родитель по своему состоянию на момент
+  `touchend`. `touchcancel` навигацию не вызывает.
+
+---
+
+## Дизайн-токены
+
+У `Viewport` нет собственных цветовых дизайн-токенов.
+
+`--triplex-next-runtime-carousel-viewport-padding` — внутренняя runtime-переменная
+с нормализованным `viewportPadding` родителя. Это не дизайн-токен, её не нужно
+добавлять в `ThemeProvider` или генерируемые файлы тем. Значение из контекста
+имеет приоритет над одноимённым свойством в `style` потребителя.
+
+---
+
+## Инварианты
+
+- Сохраняются `forwardRef`, корневой `<div>`, ref-target `HTMLDivElement`,
+  `displayName="Carousel.Viewport"`, класс `viewPort` и публичный
+  `ICarouselViewportProps`. Объединение внешнего ref с ref контекста обязательно
+  для измерений родителя; при размонтировании оба получают `null`.
+- Контекст содержит один ref области и один ref ленты; несколько областей
+  в одном родителе не поддерживаются.
+- Имя runtime-переменной padding и существующие barrel-экспорты сохраняются.
+- Код остаётся совместимым с React 17.
+
+---
+
+## Accessibility
+
+- Область — обычный `<div>` без встроенной роли, `tabIndex`, ARIA-текста
+  или клавиатурной обработки. Для имени композиции при необходимости задай
+  `role="region"` и `aria-label` родителю; язык выбирает потребитель.
+- Горизонтальная область использует `touch-action: pan-y`, вертикальная —
+  `pan-x`.
+- Клавиатурная навигация — через [CarouselPrevButton](CarouselPrevButton-ai.md) /
+  [CarouselNextButton](CarouselNextButton-ai.md) и, в `PAGE`,
+  [CarouselIndicators](CarouselIndicators-ai.md).
+- `overflow: hidden` не исключает невидимые слайды из accessibility-дерева
+  и Tab-порядка. `aria-hidden` / `inert`, связи слайдов с индикаторами,
+  управление фокусом и объявления смены слайда автоматически не создаются.
+
+---
+
+## Связанные компоненты
+
+- [Carousel](Carousel-ai.md) — родитель, владелец геометрии, состояния и
+  навигации; публично предоставляет область как `.Viewport`.
+- `Carousel.Track` — вложенный `<div role="presentation">`, располагает
+  слайды и применяет постоянное смещение из контекста. Во время жеста
+  `Viewport` временно управляет его inline `transform` / `transition`.
+- [CarouselItem](CarouselItem-ai.md) — слайд с последовательным `index`,
+  регистрируется для измерений родителя.
+- [CarouselPrevButton](CarouselPrevButton-ai.md) /
+  [CarouselNextButton](CarouselNextButton-ai.md) — кнопки перехода.
+- [CarouselIndicators](CarouselIndicators-ai.md) — навигация по страницам `PAGE`.
+
+---
+
+## Stories
+
+Основные истории: `stories/Carousel/Carousel.stories.tsx`
+Файлы примеров: `stories/Carousel/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Выбор ориентации и режима прокрутки родителя |
+| `Default` | `Default.tsx` | Горизонтальная область с лентой и кнопками внутри |
+| `ScrollModes` | `ScrollModes.tsx` | Область в `ITEM` и `PAGE`, индикаторы рядом с ней |
+| `Orientations` | `Orientations.tsx` | Горизонтальная и вертикальная области с ограниченной высотой |
+| `Production` | `Production.tsx` | Отступы области через `viewportPadding={8}` родителя |
+| `DynamicIndicators` | `DynamicIndicators.tsx` | Постраничная лента с большим количеством элементов |
+| `VisualTests` | `VisualTests.tsx` | Горизонтальная и вертикальная области с кнопками; снимаются только состояния кнопок |
+
+Скриншот-покрытие stories описано в [Carousel](Carousel-ai.md#stories).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-21 | Создан документ. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Carousel/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Carousel } from "@sberbusiness/triplex-next";
+
+const BASE_ITEM_STYLE: React.CSSProperties = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxSizing: "border-box",
+    borderRadius: "8px",
+    color: "#ffffff",
+    fontSize: "24px",
+    fontWeight: "bold",
+    userSelect: "none",
+};
+
+export const Default = () => {
+    const itemSizes = [92, 168, 220, 244, 252, 256, 252, 244, 220, 168, 92];
+    const items = itemSizes.map((size, index) => {
+        const totalItems = itemSizes.length;
+        const hue = (index / (totalItems - 1)) * 280;
+
+        return {
+            id: index + 1,
+            size,
+            backgroundColor: `hsl(${hue}, 50%, 50%)`,
+        };
+    });
+
+    const boxStyle: React.CSSProperties = {
+        width: "100%",
+        height: "256px",
+        maxWidth: "512px",
+    };
+
+    return (
+        <div style={boxStyle}>
+            <Carousel>
+                <Carousel.Viewport>
+                    <Carousel.Track>
+                        {items.map((item, index) => (
+                            <Carousel.Item
+                                key={item.id}
+                                index={index}
+                                style={{
+                                    ...BASE_ITEM_STYLE,
+                                    width: item.size,
+                                    height: "100%",
+                                    backgroundColor: item.backgroundColor,
+                                }}
+                            >
+                                {item.id}
+                            </Carousel.Item>
+                        ))}
+                    </Carousel.Track>
+                    <Carousel.PrevButton aria-label="Previous slide" />
+                    <Carousel.NextButton aria-label="Next slide" />
+                </Carousel.Viewport>
+            </Carousel>
+        </div>
+    );
+};
+```
+
+### ScrollModes
+
+`stories/Carousel/examples/ScrollModes.tsx`
+
+```tsx
+import React from "react";
+import { Carousel, ECarouselScrollMode } from "@sberbusiness/triplex-next";
+
+interface ScrollModeItemProps {
+    scrollMode: ECarouselScrollMode;
+}
+
+const BASE_ITEM_STYLE: React.CSSProperties = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxSizing: "border-box",
+    height: "256px",
+    borderRadius: "8px",
+    color: "#ffffff",
+    fontSize: "24px",
+    fontWeight: "bold",
+    userSelect: "none",
+};
+
+const ScrollModeItem = ({ scrollMode }: ScrollModeItemProps) => {
+    const itemSizes = [92, 168, 220, 244, 252, 256, 252, 244, 220, 168, 92];
+    const items = itemSizes.map((size, index) => {
+        const totalItems = itemSizes.length;
+        const hue = (index / (totalItems - 1)) * 280;
+
+        return {
+            id: index + 1,
+            size,
+            backgroundColor: `hsl(${hue}, 50%, 50%)`,
+        };
+    });
+
+    const containerStyle: React.CSSProperties = {
+        maxWidth: "512px",
+    };
+
+    return (
+        <div style={containerStyle}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{scrollMode.toUpperCase()}</div>
+            <Carousel scrollMode={scrollMode}>
+                <Carousel.Viewport>
+                    <Carousel.Track>
+                        {items.map((item, index) => (
+                            <Carousel.Item
+                                key={item.id}
+                                index={index}
+                                style={{
+                                    ...BASE_ITEM_STYLE,
+                                    width: item.size,
+                                    backgroundColor: item.backgroundColor,
+                                }}
+                            >
+                                {item.id}
+                            </Carousel.Item>
+                        ))}
+                    </Carousel.Track>
+                    <Carousel.PrevButton aria-label="Previous slide" />
+                    <Carousel.NextButton aria-label="Next slide" />
+                </Carousel.Viewport>
+                <Carousel.Indicators />
+            </Carousel>
+        </div>
+    );
+};
+
+const SCROLL_MODES = Object.values(ECarouselScrollMode);
+
+export const ScrollModes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SCROLL_MODES.map((scrollMode) => (
+            <ScrollModeItem key={scrollMode} scrollMode={scrollMode} />
+        ))}
+    </div>
+);
+```
+
+### Orientations
+
+`stories/Carousel/examples/Orientations.tsx`
+
+```tsx
+import React from "react";
+import { Carousel, EOrientation } from "@sberbusiness/triplex-next";
+
+interface OrientationItemProps {
+    orientation: EOrientation;
+}
+
+const BASE_ITEM_STYLE: React.CSSProperties = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxSizing: "border-box",
+    borderRadius: "8px",
+    color: "#ffffff",
+    fontSize: "24px",
+    fontWeight: "bold",
+    userSelect: "none",
+};
+
+const ORIENTATION_TO_ITEM_DIMENSIONS_MAP: Record<EOrientation, (size: number) => React.CSSProperties> = {
+    [EOrientation.HORIZONTAL]: (size) => ({
+        width: size,
+        height: "100%",
+    }),
+    [EOrientation.VERTICAL]: (size) => ({
+        width: "100%",
+        height: size / 2,
+    }),
+};
+
+const ORIENTATION_TO_GAP_MAP: Record<EOrientation, number> = {
+    [EOrientation.HORIZONTAL]: 16,
+    [EOrientation.VERTICAL]: 8,
+};
+
+const OrientationItem = ({ orientation }: OrientationItemProps) => {
+    const itemSizes = [92, 168, 220, 244, 252, 256, 252, 244, 220, 168, 92];
+    const items = itemSizes.map((size, index) => {
+        const totalItems = itemSizes.length;
+        const hue = (index / (totalItems - 1)) * 280;
+
+        return {
+            id: index + 1,
+            size,
+            backgroundColor: `hsl(${hue}, 50%, 50%)`,
+        };
+    });
+
+    const containerStyle: React.CSSProperties = {
+        maxWidth: "512px",
+    };
+
+    const viewportStyle: React.CSSProperties = {
+        height: "256px",
+    };
+
+    return (
+        <div style={containerStyle}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{orientation.toUpperCase()}</div>
+            <Carousel orientation={orientation} gap={ORIENTATION_TO_GAP_MAP[orientation]}>
+                <Carousel.Viewport style={viewportStyle}>
+                    <Carousel.Track>
+                        {items.map((item, index) => {
+                            const itemStyle: React.CSSProperties = {
+                                ...BASE_ITEM_STYLE,
+                                ...ORIENTATION_TO_ITEM_DIMENSIONS_MAP[orientation](item.size),
+                                backgroundColor: item.backgroundColor,
+                            };
+
+                            return (
+                                <Carousel.Item key={item.id} index={index} style={itemStyle}>
+                                    {item.id}
+                                </Carousel.Item>
+                            );
+                        })}
+                    </Carousel.Track>
+                    <Carousel.PrevButton aria-label="Previous slide" />
+                    <Carousel.NextButton aria-label="Next slide" />
+                </Carousel.Viewport>
+                <Carousel.Indicators />
+            </Carousel>
+        </div>
+    );
+};
+
+const ORIENTATIONS = Object.values(EOrientation);
+
+export const Orientations = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {ORIENTATIONS.map((orientation) => (
+            <OrientationItem key={orientation} orientation={orientation} />
+        ))}
+    </div>
+);
+```
+
+### Production
+
+`stories/Carousel/examples/Production.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    Carousel,
+    CardAction,
+    ECardRoundingSize,
+    ECardTheme,
+    ECardContentPaddingSize,
+    Title,
+    ETitleSize,
+    EFontWeightTitle,
+    Text,
+    ETextSize,
+    EFontType,
+    Gap,
+    Link,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+} from "@sberbusiness/triplex-next";
+import { DefaulticonStrokePrdIcon20 } from "@sberbusiness/icons-next";
+
+const CARDS_IDS = Array.from({ length: 6 }, (_, i) => i);
+
+const CardBody = () => (
+    <CardAction.Content.Body>
+        {[1, 2, 3].map((item) => (
+            <div key={item} style={{ display: "flex", alignItems: "center", marginTop: item > 1 ? "16px" : "0" }}>
+                <DefaulticonStrokePrdIcon20 paletteIndex={5} />
+                <Text size={ETextSize.B3} style={{ marginLeft: "8px" }}>
+                    List item text
+                </Text>
+            </div>
+        ))}
+        <Gap size={8} />
+        <Text tag="div" type={EFontType.SECONDARY} size={ETextSize.B4}>
+            This message provides additional context or highlights important information to note.
+        </Text>
+        <Gap size={8} />
+        <Text tag="div" type={EFontType.PRIMARY} size={ETextSize.B3}>
+            <Link onKeyDown={(event) => event.stopPropagation()} onClick={(event) => event.stopPropagation()}>
+                Link text
+            </Link>
+        </Text>
+    </CardAction.Content.Body>
+);
+
+export const Production = () => {
+    const [selectedId, setSelectedId] = useState<number | null>(null);
+
+    return (
+        <div style={{ width: "100%", maxWidth: "752px" }}>
+            <Carousel viewportPadding={8}>
+                <Carousel.Viewport>
+                    <Carousel.Track>
+                        {CARDS_IDS.map((id, index) => {
+                            const selected = selectedId === id;
+
+                            return (
+                                <Carousel.Item
+                                    key={id}
+                                    index={index}
+                                    style={{
+                                        width: "216px",
+                                        height: "100%",
+                                        boxSizing: "border-box",
+                                    }}
+                                >
+                                    <CardAction
+                                        roundingSize={ECardRoundingSize.MD}
+                                        theme={ECardTheme.GENERAL}
+                                        selected={selected}
+                                        toggle={() => setSelectedId(selected ? null : id)}
+                                    >
+                                        <CardAction.Media
+                                            style={{
+                                                backgroundImage: "url(assets/images/evotor.png)",
+                                                height: "129px",
+                                            }}
+                                        />
+                                        <CardAction.Content paddingSize={ECardContentPaddingSize.SM}>
+                                            <CardAction.Content.Header>
+                                                <Title tag="div" size={ETitleSize.H3} weight={EFontWeightTitle.REGULAR}>
+                                                    Title Text
+                                                </Title>
+                                            </CardAction.Content.Header>
+
+                                            <CardBody />
+
+                                            <CardAction.Content.Footer>
+                                                <Button
+                                                    theme={
+                                                        selected ? EButtonTheme.SECONDARY_LIGHT : EButtonTheme.SECONDARY
+                                                    }
+                                                    size={EComponentSize.SM}
+                                                    onKeyDown={(event) => event.stopPropagation()}
+                                                    onClick={(event) => event.stopPropagation()}
+                                                >
+                                                    Button text
+                                                </Button>
+                                            </CardAction.Content.Footer>
+                                        </CardAction.Content>
+                                    </CardAction>
+                                </Carousel.Item>
+                            );
+                        })}
+                    </Carousel.Track>
+                    <Carousel.PrevButton aria-label="Previous slide" />
+                    <Carousel.NextButton aria-label="Next slide" />
+                </Carousel.Viewport>
+            </Carousel>
+        </div>
+    );
+};
+```
+
+### DynamicIndicators
+
+`stories/Carousel/examples/DynamicIndicators.tsx`
+
+```tsx
+import React from "react";
+import { Carousel, ECarouselScrollMode } from "@sberbusiness/triplex-next";
+
+const BASE_ITEM_STYLE: React.CSSProperties = {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    boxSizing: "border-box",
+    borderRadius: "8px",
+    color: "#ffffff",
+    fontSize: "24px",
+    fontWeight: "bold",
+    userSelect: "none",
+};
+
+export const DynamicIndicators = () => {
+    const itemSizes = Array.from({ length: 20 }, () => 128);
+
+    const items = itemSizes.map((size, index) => {
+        const totalItems = itemSizes.length;
+        const hue = (index / (totalItems - 1)) * 280;
+
+        return {
+            id: index + 1,
+            size,
+            backgroundColor: `hsl(${hue}, 50%, 50%)`,
+        };
+    });
+
+    const boxStyle: React.CSSProperties = {
+        display: "flex",
+        flexDirection: "column",
+        gap: "16px",
+        width: "100%",
+        maxWidth: "512px",
+    };
+
+    const containerStyle: React.CSSProperties = {
+        width: "100%",
+        height: "256px",
+    };
+
+    return (
+        <div style={boxStyle}>
+            <div style={containerStyle}>
+                <Carousel scrollMode={ECarouselScrollMode.PAGE}>
+                    <Carousel.Viewport>
+                        <Carousel.Track>
+                            {items.map((item, index) => (
+                                <Carousel.Item
+                                    key={item.id}
+                                    index={index}
+                                    style={{
+                                        ...BASE_ITEM_STYLE,
+                                        width: item.size,
+                                        height: "100%",
+                                        backgroundColor: item.backgroundColor,
+                                    }}
+                                >
+                                    {item.id}
+                                </Carousel.Item>
+                            ))}
+                        </Carousel.Track>
+                        <Carousel.PrevButton aria-label="Previous slide" />
+                        <Carousel.NextButton aria-label="Next slide" />
+                    </Carousel.Viewport>
+                    <Carousel.Indicators />
+                </Carousel>
+            </div>
+        </div>
+    );
+};
+```
+