@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/ImageSlider/ImageSlider.tsx

@@ -0,0 +1,582 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useCallback, useMemo, useState, type CSSProperties } from 'react';
+
+import { IndexIndicator } from './components/IndexIndicator/IndexIndicator';
+import { NavigationButtons } from './components/NavigationButtons/NavigationButtons';
+import { ResponsiveImage } from './components/ResponsiveImage';
+import { Thumbnails } from './components/Thumbnails/Thumbnails';
+import { PLACEHOLDER_EMPTY_CARDS } from './constants';
+import { useImageSlider } from './hooks/useImageSlider';
+import { useImageSliderNavigation } from './hooks/useImageSliderNavigation';
+import { useImageSliderScrollHandler } from './hooks/useImageSliderScrollHandler';
+import {
+    ImageSliderAnalyticsEvent,
+    ImageSliderCard,
+    ResponsiveImageConfig,
+    ThumbnailDisplay,
+} from './ImageSlider.types';
+import { generateThumbnailSizesAttribute, generateThumbnailSrcSet } from './utils/imageOptimization';
+
+type Props = {
+    /**
+     * The scrollable content of the image slider.
+     * Should be individual images.
+     *
+     * @property {ReactNode} card - The rendered image content
+     * @property {string} key - A unique identifier for the image
+     */
+    cards: ImageSliderCard[];
+    /**
+     * Class name for the image gallery container.
+     */
+    className?: string;
+    /**
+     * Optional key to identify when content has changed (e.g., an item id).
+     * When this key changes, the slider will reset to the first image.
+     * If not provided, will reset whenever the cards array reference changes.
+     */
+    contentKey?: string | number;
+    /**
+     * Shape of the navigation icons.
+     * 'circle' creates round buttons, 'square' creates square buttons.
+     *
+     * @default 'circle'
+     */
+    iconShape?: 'circle' | 'square';
+    /**
+     * Size of the navigation icons - sm=34px, md=42px, lg=54px.
+     * For horizontal thumbnails, 'lg' (54px) is recommended.
+     *
+     * @default 'sm'
+     */
+    iconSize?: 'sm' | 'md' | 'lg';
+    /**
+     * Type of icons to use for navigation.
+     * 'caret' uses CaretLeft/CaretRight, 'arrow' uses ArrowLeft/ArrowRight.
+     *
+     * @default 'caret'
+     */
+    iconType?: 'caret' | 'arrow';
+    /**
+     * Variant of the navigation icons.
+     * 'outlined' shows buttons with borders, 'transparent' shows borderless buttons.
+     *
+     * @default 'outlined'
+     */
+    iconVariant?: 'outlined' | 'transparent';
+    /**
+     * When thumbnailDisplay is 'index', position of the numeric indicator relative to the main image.
+     *
+     * @default 'bottom'
+     */
+    indexPosition?: 'top' | 'bottom';
+    /**
+     * Callback fired when an analytics event occurs in the image slider.
+     * Receives interaction type, current image position (1-based), and total image count.
+     * Does not fire for mobile swipe navigation, only for button/thumbnail clicks and lightbox opens.
+     */
+    onAnalyticsEventTriggered?: (event: ImageSliderAnalyticsEvent) => void;
+    /**
+     * Callback fired when an image is clicked (mouse) or activated via keyboard (Enter/Space).
+     * Receives the index of the image and the mouse or keyboard event.
+     */
+    onImageClick?: (
+        imageIndex: number,
+        event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>
+    ) => void;
+    /**
+     * Callback fired when an image is hovered (mouse) or focused (keyboard/screen reader).
+     * Receives the index of the image and the mouse or focus event.
+     */
+    onImageMouseOver?: (
+        imageIndex: number,
+        event: React.MouseEvent<HTMLElement> | React.FocusEvent<HTMLElement>
+    ) => void;
+    /**
+     * Configuration for responsive image loading when using imageData in cards.
+     * Defines mobile/desktop sizes and breakpoint for optimal image loading.
+     */
+    responsiveImageConfig?: ResponsiveImageConfig;
+    /**
+     * Displays thumbnail previews on the left side of the slider.
+     * Clicking a thumbnail will navigate to the corresponding image.
+     * The current image thumbnail will have a border highlight.
+     *
+     * @default true
+     */
+    showThumbnails?: boolean;
+    /**
+     * Display mode for image navigation controls.
+     * 'thumbnails' shows image previews (vertical or horizontal per thumbnailOrientation).
+     * 'index' shows a numeric indicator (e.g., "1 of 11") above or below the main image per indexPosition.
+     *
+     * @default ThumbnailDisplay.Thumbnails
+     */
+    thumbnailDisplay?: ThumbnailDisplay;
+    /**
+     * Orientation of the thumbnail previews when showThumbnails is true.
+     * 'vertical' displays thumbnails on the left side, 'horizontal' displays them below the image.
+     *
+     * @default 'vertical'
+     */
+    thumbnailOrientation?: 'vertical' | 'horizontal';
+};
+
+/**
+ * Displays a single image at a time with navigation controls.
+ * Allows navigation via buttons, dots (pagination), or touch gestures (on mobile).
+ */
+// Default responsive image configuration
+const DEFAULT_RESPONSIVE_CONFIG: ResponsiveImageConfig = {
+    breakpoint: 768,
+    desktopSize: 651,
+    mobileSize: 366,
+};
+
+export const ImageSlider = ({
+    cards: initialCards,
+    className,
+    contentKey,
+    iconShape = 'circle',
+    iconSize = 'sm',
+    iconType = 'caret',
+    iconVariant = 'outlined',
+    indexPosition = 'bottom',
+    onAnalyticsEventTriggered,
+    onImageClick,
+    onImageMouseOver,
+    responsiveImageConfig = DEFAULT_RESPONSIVE_CONFIG,
+    showThumbnails = true,
+    thumbnailDisplay = ThumbnailDisplay.Thumbnails,
+    thumbnailOrientation = 'vertical',
+}: Props) => {
+    // When an item doesn't have images, the cards array will be empty.
+    // We need to show a placeholder empty card in this case.
+    const cards = useMemo(() => {
+        if (initialCards.length === 0) {
+            return PLACEHOLDER_EMPTY_CARDS;
+        }
+        return initialCards;
+    }, [initialCards]);
+
+    const numberOfPages = cards.length;
+
+    // Initialize base slider state and refs
+    const {
+        containerRef,
+        contentRef,
+        handleMobileInteraction,
+        handleMouseOver,
+        hasHoveredGallery,
+        isMobile,
+        setHasHoveredGallery,
+    } = useImageSlider({
+        numberOfPages,
+        responsiveImageConfig,
+    });
+
+    // Manage scrolling state locally to avoid circular dependency
+    const [isScrolling, setIsScrolling] = useState(false);
+
+    // Initialize navigation state and handlers
+    const navigation = useImageSliderNavigation({
+        cards,
+        contentKey,
+        contentRef,
+        isScrolling,
+        numberOfPages,
+        setHasHoveredGallery,
+        thumbnailDisplay,
+        thumbnailOrientation,
+    });
+
+    // Initialize scroll handling with navigation state and local setIsScrolling
+    const { onScrollCards } = useImageSliderScrollHandler({
+        contentRef,
+        currentPage: navigation.currentPage,
+        maxMobileCardWidth: responsiveImageConfig.desktopSize,
+        numberOfPages,
+        setCurrentPage: navigation.setCurrentPage,
+        setIsScrolling,
+    });
+
+    // Extract all the values we need
+    const {
+        currentPage,
+        goToNextPage,
+        goToPreviousPage,
+        handleThumbnailClick,
+        isNextPageDisabled,
+        isPreviousPageDisabled,
+        onKeyNavigation,
+        showNextPageButton,
+        showPreviousPageButton,
+    } = navigation;
+
+    // Wrap navigation handlers to trigger analytics
+    const goToNextPageWithAnalytics = useCallback(() => {
+        goToNextPage();
+        onAnalyticsEventTriggered?.({
+            imagePosition: currentPage < numberOfPages ? currentPage + 1 : 1,
+            interactionType: 'Next',
+            totalImages: numberOfPages,
+        });
+    }, [goToNextPage, onAnalyticsEventTriggered, currentPage, numberOfPages]);
+
+    const goToPreviousPageWithAnalytics = useCallback(() => {
+        goToPreviousPage();
+        onAnalyticsEventTriggered?.({
+            imagePosition: currentPage > 1 ? currentPage - 1 : numberOfPages,
+            interactionType: 'Prev',
+            totalImages: numberOfPages,
+        });
+    }, [goToPreviousPage, onAnalyticsEventTriggered, currentPage, numberOfPages]);
+
+    const handleThumbnailClickWithAnalytics = useCallback(
+        (pageNumber: number) => {
+            // Only trigger analytics if navigating to a different image
+            if (pageNumber !== currentPage && onAnalyticsEventTriggered) {
+                onAnalyticsEventTriggered({
+                    imagePosition: pageNumber,
+                    interactionType: 'Thumbnail Click',
+                    totalImages: numberOfPages,
+                });
+            }
+            handleThumbnailClick(pageNumber);
+        },
+        [currentPage, handleThumbnailClick, onAnalyticsEventTriggered, numberOfPages]
+    );
+
+    /**
+     * These images are wrapped in a div and displayed one at a time with proper snap behavior.
+     * When showImageOverflow is enabled on mobile, images take partial width to show overflow.
+     * Supports both custom ReactNode cards and responsive imageData.
+     * Images are re-rendered when currentPage changes to ensure active image gets full quality.
+     *
+     * On desktop before hover: Only render first image to avoid loading second image unnecessarily.
+     * On mobile: Always render all images for swipe functionality.
+     * After hover on desktop: Render all images for navigation.
+     */
+    const carouselCards = useMemo(() => {
+        // On desktop before hover, only render the first image to prevent unnecessary loading
+        // On mobile or after hover, render all images
+        const cardsToRender = !isMobile && !hasHoveredGallery ? cards.slice(0, 1) : cards;
+
+        return cardsToRender.map(({ card, imageData, key }, index) => {
+            // For the sliced scenario, we need to get the actual index from the original cards array
+            const actualIndex = !isMobile && !hasHoveredGallery ? 0 : index;
+            const isActive = actualIndex + 1 === currentPage;
+
+            return (
+                <div
+                    aria-current={isActive ? 'true' : 'false'}
+                    aria-label={`Image ${actualIndex + 1} of ${cards.length}${imageData?.alt ? `: ${imageData.alt}` : ''}`}
+                    className={cn(
+                        'flex w-full flex-none snap-center items-center justify-center bg-background-primary',
+                        onImageClick ? 'cursor-zoom-in' : 'cursor-default',
+                        // Desktop: full height
+                        'smMin:h-full',
+                        // Mobile-specific styling (xsMax) — max dimensions follow responsiveImageConfig.desktopSize via --slider-size
+                        'xsMax:aspect-square xsMax:max-h-[var(--slider-size)] xsMax:max-w-[var(--slider-size)] xsMax:overflow-hidden xsMax:rounded-lg xsMax:border xsMax:border-border-secondary',
+                        // Apply width reduction only when there are multiple cards for bleed effect
+                        numberOfPages > 1
+                            ? 'xsMax:w-[calc(100%-64px)] xsMax:max-w-[var(--slider-size)]'
+                            : 'xsMax:w-full xsMax:max-w-[var(--slider-size)]',
+                        {
+                            'ml-sm': actualIndex === 0,
+                            'mr-sm': actualIndex === cards.length - 1,
+                        }
+                    )}
+                    key={key} // Use stable key to avoid unnecessary DOM recreations
+                    onClick={(event) => {
+                        // Trigger mobile interaction for high-quality loading
+                        handleMobileInteraction();
+                        // Trigger analytics for lightbox open
+                        if (onAnalyticsEventTriggered) {
+                            onAnalyticsEventTriggered({
+                                imagePosition: actualIndex + 1,
+                                interactionType: 'Open Lightbox',
+                                totalImages: numberOfPages,
+                            });
+                        }
+                        // Call optional user-provided handler
+                        onImageClick?.(actualIndex, event);
+                    }}
+                    onFocus={(event) => {
+                        // Trigger mobile interaction for high-quality loading
+                        handleMobileInteraction();
+                        // Call optional user-provided handler
+                        onImageMouseOver?.(actualIndex, event);
+                    }}
+                    onKeyUp={
+                        onImageClick
+                            ? (event) => {
+                                  if (event.key === 'Enter' || event.key === ' ') {
+                                      event.preventDefault();
+                                      // Trigger analytics for lightbox open via keyboard
+                                      if (onAnalyticsEventTriggered) {
+                                          onAnalyticsEventTriggered({
+                                              imagePosition: actualIndex + 1,
+                                              interactionType: 'Open Lightbox',
+                                              totalImages: numberOfPages,
+                                          });
+                                      }
+                                      if (event.key === 'Enter') {
+                                          onImageClick(actualIndex, event);
+                                      }
+                                  }
+                              }
+                            : undefined
+                    }
+                    onMouseOver={(event) => {
+                        // Always trigger gallery hover state for high-quality loading
+                        handleMouseOver();
+                        // Call optional user-provided handler
+                        if (onImageMouseOver) {
+                            onImageMouseOver(actualIndex, event);
+                        }
+                    }}
+                    onTouchStart={() => {
+                        // Trigger mobile interaction for high-quality loading on touch/drag
+                        handleMobileInteraction();
+                    }}
+                    role={onImageClick ? 'button' : undefined}
+                    tabIndex={onImageClick ? 0 : undefined}
+                >
+                    {/* Render responsive image if imageData is provided, otherwise use custom card */}
+                    {imageData ? (
+                        <ResponsiveImage
+                            hasHoveredGallery={hasHoveredGallery}
+                            imageData={imageData}
+                            isActiveImage={isActive}
+                            isMainImage
+                            responsiveImageConfig={responsiveImageConfig}
+                        />
+                    ) : (
+                        card || null
+                    )}
+                </div>
+            );
+        });
+    }, [
+        cards,
+        currentPage,
+        handleMobileInteraction,
+        handleMouseOver,
+        hasHoveredGallery,
+        isMobile,
+        numberOfPages,
+        onAnalyticsEventTriggered,
+        onImageClick,
+        onImageMouseOver,
+        responsiveImageConfig,
+    ]);
+
+    const isIndexDisplay = thumbnailDisplay === ThumbnailDisplay.Index;
+    const isHorizontalThumbnailsDisplay =
+        thumbnailDisplay === ThumbnailDisplay.Thumbnails && thumbnailOrientation === 'horizontal';
+
+    return (
+        // eslint-disable-next-line jsx-a11y/no-static-element-interactions, jsx-a11y/mouse-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/tabindex-no-positive
+        <section
+            aria-label="Image gallery"
+            aria-roledescription="carousel"
+            className={cn(
+                'relative mx-auto w-full pr-lg outline-none smMax:pr-0',
+                // Only extend beyond viewport for bleed effect when there are multiple cards
+                { 'xsMax:-ml-sm xsMax:w-[calc(100%+32px)]': numberOfPages > 1 },
+                className
+            )}
+            onClick={() => containerRef.current?.focus()}
+            onKeyUp={onKeyNavigation}
+            onMouseOver={handleMouseOver}
+            ref={containerRef}
+            role="application"
+            style={
+                {
+                    '--slider-size': `${responsiveImageConfig.desktopSize}px`,
+                } as CSSProperties
+            }
+            // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+            tabIndex={0}
+        >
+            <div
+                className={cn(
+                    'flex flex-col',
+                    // Dynamic gap that scales smoothly from ~58px down to smaller sizes
+                    'gap-[58px] mdMax:gap-xl smMax:gap-[38px] xsMax:gap-[28px]'
+                )}
+            >
+                {/* Image Gallery Container */}
+                <div
+                    className={cn(
+                        'flex w-full',
+                        thumbnailDisplay === ThumbnailDisplay.Index
+                            ? 'flex-col items-center justify-center gap-2xs'
+                            : thumbnailOrientation === 'horizontal'
+                              ? 'flex-col items-center justify-center gap-xs'
+                              : 'relative items-center justify-center gap-[28px]'
+                    )}
+                >
+                    {/* Index indicator - above main image when thumbnailDisplay is 'index' and indexPosition is 'top' */}
+                    {thumbnailDisplay === ThumbnailDisplay.Index && indexPosition === 'top' && (
+                        <IndexIndicator
+                            currentPage={currentPage}
+                            numberOfPages={numberOfPages}
+                        />
+                    )}
+
+                    {/* Vertical Thumbnails Container - Absolutely positioned */}
+                    {showThumbnails &&
+                        thumbnailDisplay === ThumbnailDisplay.Thumbnails &&
+                        thumbnailOrientation === 'vertical' && (
+                            <div className="absolute bottom-0 left-0 top-0 z-10 xsMax:hidden">
+                                <Thumbnails
+                                    cards={cards}
+                                    currentPage={currentPage}
+                                    generateThumbnailSizesAttribute={generateThumbnailSizesAttribute}
+                                    generateThumbnailSrcSet={generateThumbnailSrcSet}
+                                    onThumbnailClick={handleThumbnailClickWithAnalytics}
+                                    orientation="vertical"
+                                />
+                            </div>
+                        )}
+
+                    {/* Main Image Area */}
+                    <div
+                        className={cn(
+                            'flex items-center',
+                            isIndexDisplay
+                                ? 'relative w-full justify-center gap-md smMin:max-w-[780px] xsMax:w-full'
+                                : isHorizontalThumbnailsDisplay
+                                  ? 'max-w-[606px] gap-md xsMax:w-full'
+                                  : cn(
+                                        'w-full justify-between gap-sm',
+                                        showThumbnails ? 'pl-[146px] mdMax:pl-[139px] xsMax:pl-0' : ''
+                                    )
+                        )}
+                        data-testid="image-slider-hero-controls"
+                    >
+                        {/* Desktop navigation buttons (left) - hidden on mobile */}
+                        <div className="hidden smMin:block">
+                            <NavigationButtons
+                                goToNextPage={goToNextPageWithAnalytics}
+                                goToPreviousPage={goToPreviousPageWithAnalytics}
+                                iconShape={iconShape}
+                                iconSize={iconSize}
+                                iconType={iconType}
+                                iconVariant={iconVariant}
+                                isNextPageDisabled={isNextPageDisabled}
+                                isPreviousPageDisabled={isPreviousPageDisabled}
+                                position="left"
+                                showNextPageButton={showNextPageButton}
+                                showPreviousPageButton={showPreviousPageButton}
+                            />
+                        </div>
+
+                        {/* Main image container - responsive layout */}
+                        <div
+                            className={cn(
+                                // Shared: relative container with consistent max dimensions
+                                'relative',
+                                isIndexDisplay
+                                    ? 'max-h-[var(--slider-size)] smMin:flex smMin:aspect-square smMin:max-w-[var(--slider-size)] smMin:flex-1 smMin:justify-center smMin:overflow-hidden xsMax:w-full'
+                                    : isHorizontalThumbnailsDisplay
+                                      ? 'max-h-[400px] smMin:flex smMin:aspect-square smMin:max-w-[400px] smMin:flex-1 smMin:justify-center smMin:overflow-hidden xsMax:w-full'
+                                      : 'max-h-[var(--slider-size)] smMin:flex smMin:aspect-square smMin:max-w-[var(--slider-size)] smMin:flex-1 smMin:justify-center smMin:overflow-hidden xsMax:w-full'
+                            )}
+                            data-testid="image-slider-media-frame"
+                        >
+                            {/* Mobile navigation buttons - hidden on desktop */}
+                            <div className="smMin:hidden">
+                                <NavigationButtons
+                                    goToNextPage={goToNextPageWithAnalytics}
+                                    goToPreviousPage={goToPreviousPageWithAnalytics}
+                                    iconShape={iconShape}
+                                    iconSize={iconSize}
+                                    iconType={iconType}
+                                    iconVariant={iconVariant}
+                                    isNextPageDisabled={isNextPageDisabled}
+                                    isPreviousPageDisabled={isPreviousPageDisabled}
+                                    showNextPageButton={showNextPageButton}
+                                    showPreviousPageButton={showPreviousPageButton}
+                                />
+                            </div>
+
+                            {/* Responsive scroll container wrapper */}
+                            <div
+                                className={cn(
+                                    // Shared: primary background and full width
+                                    'w-full bg-background-primary',
+                                    // Desktop: full height and hidden overflow
+                                    'smMin:h-full smMin:overflow-hidden'
+                                )}
+                            >
+                                <div
+                                    aria-atomic="false"
+                                    aria-live="polite"
+                                    className={cn(
+                                        'flex w-full snap-x snap-mandatory overflow-y-hidden overflow-x-scroll',
+                                        // Desktop: full height and 24px gap
+                                        'smMin:h-full smMin:gap-md',
+                                        // Mobile: 2xs gap, let aspect-square control height
+                                        'xsMax:gap-2xs'
+                                    )}
+                                    onScroll={onScrollCards}
+                                    ref={contentRef}
+                                    role="region"
+                                    style={{
+                                        scrollbarWidth: 'none',
+                                    }}
+                                >
+                                    {carouselCards}
+                                </div>
+                            </div>
+                        </div>
+
+                        {/* Desktop navigation buttons (right) - hidden on mobile */}
+                        <div className="hidden smMin:block">
+                            <NavigationButtons
+                                goToNextPage={goToNextPageWithAnalytics}
+                                goToPreviousPage={goToPreviousPageWithAnalytics}
+                                iconShape={iconShape}
+                                iconSize={iconSize}
+                                iconType={iconType}
+                                iconVariant={iconVariant}
+                                isNextPageDisabled={isNextPageDisabled}
+                                isPreviousPageDisabled={isPreviousPageDisabled}
+                                position="right"
+                                showNextPageButton={showNextPageButton}
+                                showPreviousPageButton={showPreviousPageButton}
+                            />
+                        </div>
+                    </div>
+
+                    {/* Horizontal Thumbnails Container - Below image */}
+                    {showThumbnails &&
+                        thumbnailDisplay === ThumbnailDisplay.Thumbnails &&
+                        thumbnailOrientation === 'horizontal' && (
+                            <div className="w-full xsMax:hidden">
+                                <Thumbnails
+                                    cards={cards}
+                                    currentPage={currentPage}
+                                    generateThumbnailSizesAttribute={generateThumbnailSizesAttribute}
+                                    generateThumbnailSrcSet={generateThumbnailSrcSet}
+                                    onThumbnailClick={handleThumbnailClickWithAnalytics}
+                                    orientation="horizontal"
+                                />
+                            </div>
+                        )}
+
+                    {/* Index indicator - below main image when thumbnailDisplay is 'index' and indexPosition is 'bottom' */}
+                    {thumbnailDisplay === ThumbnailDisplay.Index && indexPosition === 'bottom' && (
+                        <IndexIndicator
+                            currentPage={currentPage}
+                            numberOfPages={numberOfPages}
+                        />
+                    )}
+                </div>
+            </div>
+        </section>
+    );
+};

package/src/ImageSlider/ImageSlider.types.ts

@@ -0,0 +1,90 @@
+import { ReactNode } from 'react';
+
+/**
+ * Display mode for thumbnail navigation
+ */
+export enum ThumbnailDisplay {
+    Index = 'index',
+    Thumbnails = 'thumbnails',
+}
+
+/**
+ * Analytics event data for ImageSlider interactions
+ */
+export type ImageSliderAnalyticsEvent = {
+    /** Current image position (1-based index) */
+    imagePosition: number;
+    /** Type of interaction that triggered the event */
+    interactionType: 'Thumbnail Click' | 'Next' | 'Prev' | 'Open Lightbox';
+    /** Total number of images in the slider */
+    totalImages: number;
+};
+
+/**
+ * Responsive image data for optimized loading
+ */
+export type ResponsiveImageData = {
+    /**
+     * Alt text for the image
+     */
+    alt: string;
+    /**
+     * Base URL for the image (without width parameters)
+     */
+    baseUrl: string;
+    /**
+     * Optional title for the image
+     */
+    title?: string;
+};
+
+/**
+ * Configuration for responsive image sizes and breakpoints
+ */
+export type ResponsiveImageConfig = {
+    /**
+     * Breakpoint width in pixels where mobile switches to desktop
+     * @default 768
+     */
+    breakpoint: number;
+    /**
+     * Desktop image width in pixels
+     * @default 651
+     */
+    desktopSize: number;
+    /**
+     * Mobile image width in pixels
+     * @default 366
+     */
+    mobileSize: number;
+};
+
+/**
+ * Card for the ImageSlider - supports both custom ReactNode and responsive images
+ */
+export type ImageSliderCard = {
+    /**
+     * The rendered content of the card or image.
+     * Optional when using imageData.
+     */
+    card?: ReactNode;
+    /**
+     * Responsive image data for automatic srcset/sizes optimization.
+     * When provided, `card` will be ignored and an optimized <img> will be rendered.
+     * Optional when using custom card content.
+     */
+    imageData?: ResponsiveImageData;
+    /**
+     * The unique identifier for the card
+     */
+    key: string;
+};
+
+export type ImageSliderPageInfo = {
+    breakpoints: number[];
+    cardsPerPage: number;
+    numberOfPages: number;
+};
+
+// this is the px size of the MD gap (kept for potential future use)
+export const CAROUSEL_CARD_GAP_NUM = 24;