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

package/bundle/components/CarouselItem.md

@@ -0,0 +1,579 @@
+---
+component: CarouselItem
+category: Carousel
+related: [Carousel]
+tokens: []
+stories: stories/Carousel/Carousel.stories.tsx
+version: "1.0"
+---
+
+# CarouselItem
+
+## Назначение
+
+Слайд составного `Carousel`. Регистрирует свой DOM-узел по `index`, по этим
+узлам родитель измеряет слайды и рассчитывает страницы и границы прокрутки.
+
+Используй внутри `Carousel.Track`, вложенного в `Carousel.Viewport`.
+Не используй вне `Carousel`: без родителя слайд не измеряется и не участвует
+в навигации.
+
+Доступен только как `Carousel.Item`: именованного экспорта `CarouselItem`
+из пакета нет, `ICarouselItemProps` экспортируется.
+
+```tsx
+import { Carousel } from "@sberbusiness/triplex-next";
+
+<Carousel style={{ width: 320, height: 180 }}>
+    <Carousel.Viewport>
+        <Carousel.Track>
+            {items.map((item, index) => (
+                <Carousel.Item key={item.id} index={index} aria-label={item.title} style={{ width: 280 }}>
+                    {item.title}
+                </Carousel.Item>
+            ))}
+        </Carousel.Track>
+    </Carousel.Viewport>
+</Carousel>
+```
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `index` | `number` | Позиция слайда с нуля. Ключ регистрации для геометрии, не HTML-атрибут |
+
+Остальные props — атрибуты `<div>`, передаются на корень слайда.
+
+### Индексы
+
+- Индексы уникальны, идут подряд (`0, 1, 2, …`) и совпадают с DOM-порядком.
+  Пропуск, дубликат или несовпадение с порядком ломают расчёт страниц;
+  компонент такой ввод не проверяет.
+- `index` берётся из позиции в `map`, `key` — из стабильного id данных. После
+  удаления, вставки или перестановки потребитель пересчитывает индексы.
+- Регистрация не запускает пересчёт геометрии. Кэш размеров слайдов
+  сбрасывается при изменении размеров `Viewport` или `Track`
+  (`ResizeObserver`) и при смене `gap`, `scrollMode` или `orientation`:
+  после перестановки слайдов без этих изменений в кэше остаются прежние
+  размеры по индексам.
+- Размер слайда задаёт потребитель или содержимое; родитель измеряет ширину
+  в горизонтальной карусели и высоту в вертикальной.
+
+---
+
+## Дизайн-токены
+
+Собственных токенов нет.
+
+---
+
+## Инварианты
+
+- `forwardRef` указывает на корневой `<div>` слайда; внешний ref объединяется
+  с регистрационным callback.
+- `displayName` — `"Carousel.Item"`, CSS-класс — `slide`.
+- При смене `index` и размонтировании прежняя запись удаляется из реестра:
+  родитель считает слайды по числу записей, а не по `children`.
+- `role="group"` задан до spread, потребитель может его переопределить.
+
+---
+
+## Accessibility
+
+- Роль по умолчанию — `group`; доступное имя задаёт потребитель через
+  `aria-label` или `aria-labelledby`.
+- `index` не даёт `aria-posinset` / `aria-setsize` и связей с индикаторами.
+- Слайды за пределами видимой области не получают `aria-hidden`, `inert`
+  или `tabIndex={-1}`: их содержимое остаётся в Tab-порядке.
+
+---
+
+## Связанные компоненты
+
+- `Carousel` — владелец контекста, геометрии и навигации.
+- `Carousel.Track` — лента слайдов, задаёт `gap` и смещение.
+- `Carousel.Viewport` — видимая область и touch-жесты.
+
+---
+
+## 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` | Слайды с карточками и вложенными кнопками |
+| `DynamicIndicators` | `DynamicIndicators.tsx` | Длинная лента слайдов |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-20 | Создан документ |
+
+---
+
+## Примеры использования
+
+### 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>
+    );
+};
+```
+