@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/ImageSlider/components/IndexIndicator/IndexIndicator.tsx

@@ -0,0 +1,21 @@
+type Props = {
+    /** Currently active page number (1-based) */
+    currentPage: number;
+    /** Total number of pages/images */
+    numberOfPages: number;
+};
+
+/**
+ * Displays a numeric index indicator (e.g., "1 of 11") for image gallery position.
+ * Used when thumbnailDisplay is 'index' instead of image thumbnails.
+ */
+export const IndexIndicator = ({ currentPage, numberOfPages }: Props) => (
+    <div
+        aria-label={`Image ${currentPage} of ${numberOfPages}`}
+        aria-live="polite"
+        className="hui-text-caption flex justify-center text-text-secondary"
+        role="status"
+    >
+        {currentPage} of {numberOfPages}
+    </div>
+);

package/src/ImageSlider/components/NavigationButtons/NavigationButtons.tsx

@@ -0,0 +1,113 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { IconButton } from '../../../IconButton/IconButton';
+import { ArrowLeft, ArrowRight, CaretLeft, CaretRight } from '../../../Icons';
+
+type Props = {
+    goToNextPage: () => void;
+    goToPreviousPage: () => void;
+    /** Shape of the navigation icons */
+    iconShape?: 'circle' | 'square';
+    /** Size of the navigation icons - sm=34px, md=42px, lg=54px */
+    iconSize?: 'sm' | 'md' | 'lg';
+    /** Type of icons to use for navigation */
+    iconType?: 'caret' | 'arrow';
+    /** Variant of the navigation icons */
+    iconVariant?: 'outlined' | 'transparent';
+    /** Whether the next button should be disabled */
+    isNextPageDisabled?: boolean;
+    /** Whether the previous button should be disabled */
+    isPreviousPageDisabled?: boolean;
+    /** For grid layout - which position this button should render (left or right) */
+    position?: 'left' | 'right';
+    showNextPageButton: boolean;
+    showPreviousPageButton: boolean;
+};
+
+export const NavigationButtons = ({
+    goToNextPage,
+    goToPreviousPage,
+    iconShape = 'circle',
+    iconSize = 'sm',
+    iconType = 'caret',
+    iconVariant = 'outlined',
+    isNextPageDisabled = false,
+    isPreviousPageDisabled = false,
+    position,
+    showNextPageButton,
+    showPreviousPageButton,
+}: Props) => {
+    // Choose the correct icons based on iconType prop
+    const LeftIcon = iconType === 'arrow' ? ArrowLeft : CaretLeft;
+    const RightIcon = iconType === 'arrow' ? ArrowRight : CaretRight;
+
+    // For grid layout with outside positioning, render individual buttons
+    if (position) {
+        if (position === 'left') {
+            return showPreviousPageButton ? (
+                <IconButton
+                    aria-label="Previous Page"
+                    className="xsMax:hidden"
+                    disabled={isPreviousPageDisabled}
+                    hideTooltip
+                    icon={LeftIcon}
+                    onClick={goToPreviousPage}
+                    shape={iconShape}
+                    size={iconSize}
+                    variant={iconVariant}
+                />
+            ) : null;
+        }
+
+        // position === 'right'
+        return showNextPageButton ? (
+            <IconButton
+                aria-label="Next Page"
+                className="xsMax:hidden"
+                disabled={isNextPageDisabled}
+                hideTooltip
+                icon={RightIcon}
+                onClick={goToNextPage}
+                shape={iconShape}
+                size={iconSize}
+                variant={iconVariant}
+            />
+        ) : null;
+    }
+
+    // Original layout for inside positioning or non-grid layouts
+    // For inside positioning: calculate from the top to put the button halfway down its parent relative to its own center.
+    // this will break if the size of the IconButton is ever changed,
+    const positionStyles = cn('absolute top-[calc(50%-21px)] w-full');
+
+    return (
+        <div className="z-10">
+            {showPreviousPageButton && (
+                <IconButton
+                    aria-label="Previous Page"
+                    className={cn(positionStyles, 'left-sm', 'xsMax:hidden')}
+                    disabled={isPreviousPageDisabled}
+                    hideTooltip
+                    icon={LeftIcon}
+                    onClick={goToPreviousPage}
+                    shape={iconShape}
+                    size={iconSize}
+                    variant={iconVariant}
+                />
+            )}
+            {showNextPageButton && (
+                <IconButton
+                    aria-label="Next Page"
+                    className={cn(positionStyles, 'right-sm', 'xsMax:hidden')}
+                    disabled={isNextPageDisabled}
+                    hideTooltip
+                    icon={RightIcon}
+                    onClick={goToNextPage}
+                    shape={iconShape}
+                    size={iconSize}
+                    variant={iconVariant}
+                />
+            )}
+        </div>
+    );
+};

package/src/ImageSlider/components/ResponsiveImage/ResponsiveImage.tsx

@@ -0,0 +1,114 @@
+import { PLACEHOLDER_IMAGE_URL } from '../../constants';
+import { ResponsiveImageConfig, ResponsiveImageData } from '../../ImageSlider.types';
+import {
+    generateMainImageSrcSet,
+    generateSizesAttribute,
+    generateThumbnailSizesAttribute,
+    generateThumbnailSrcSet,
+    getImageSrc,
+    getThumbnailSrc,
+} from '../../utils/imageOptimization';
+
+/**
+ * Props for the ResponsiveImage component
+ */
+type Props = {
+    /** Additional CSS classes */
+    className?: string;
+    /** Whether the gallery has been hovered (for quality optimization) */
+    hasHoveredGallery?: boolean;
+    /** Image data containing alt, baseUrl, and title */
+    imageData: ResponsiveImageData;
+    /** Whether this image is currently active/visible */
+    isActiveImage?: boolean;
+    /** Whether this is a main image (not a thumbnail) */
+    isMainImage?: boolean;
+    /** Responsive image configuration */
+    responsiveImageConfig?: ResponsiveImageConfig;
+};
+
+/**
+ * Renders a responsive image with optimized loading priorities and srcSet
+ */
+export const ResponsiveImage = ({
+    className,
+    hasHoveredGallery = false,
+    imageData,
+    isActiveImage = false,
+    isMainImage = true,
+    responsiveImageConfig,
+}: Props) => {
+    const { alt, baseUrl, title } = imageData;
+
+    if (!responsiveImageConfig) {
+        // Fallback to simple image if no config provided
+        return (
+            <img
+                alt={alt}
+                className={className}
+                onError={(e) => {
+                    const target = e.target as HTMLImageElement;
+                    if (target.src !== PLACEHOLDER_IMAGE_URL) {
+                        target.src = PLACEHOLDER_IMAGE_URL;
+                    }
+                }}
+                src={baseUrl}
+                title={title}
+            />
+        );
+    }
+
+    if (isMainImage) {
+        // Use high quality mode for all images once gallery has been hovered
+        const useHighQuality = hasHoveredGallery;
+
+        // Only use high quality URLs/srcSet after gallery has been hovered
+        // Active images get high priority/eager loading but still use responsive srcSet initially
+        const shouldLoadHighQuality = useHighQuality;
+
+        return (
+            <img
+                alt={alt}
+                className="h-full w-full bg-background-primary object-contain"
+                fetchPriority={isActiveImage || shouldLoadHighQuality ? 'high' : 'low'}
+                // Force React to create a new img element when switching to high quality
+                // This prevents the browser from loading both constrained and unconstrained versions
+                key={shouldLoadHighQuality && !isActiveImage ? 'high-quality' : 'standard-quality'}
+                loading={isActiveImage || shouldLoadHighQuality ? 'eager' : 'lazy'}
+                onError={(e) => {
+                    const target = e.target as HTMLImageElement;
+                    if (target.src !== PLACEHOLDER_IMAGE_URL) {
+                        target.src = PLACEHOLDER_IMAGE_URL;
+                        // Clear srcSet to prevent fallback to other sizes that might also fail
+                        target.srcset = '';
+                    }
+                }}
+                sizes={generateSizesAttribute(responsiveImageConfig, shouldLoadHighQuality)}
+                src={getImageSrc(baseUrl, responsiveImageConfig, shouldLoadHighQuality)}
+                srcSet={generateMainImageSrcSet(baseUrl, responsiveImageConfig, shouldLoadHighQuality)}
+                title={title}
+            />
+        );
+    }
+
+    // Thumbnail image - responsive sizes
+    return (
+        <img
+            alt={alt}
+            className="h-full max-h-[111px] w-full max-w-[111px] object-cover"
+            loading="lazy"
+            onError={(e) => {
+                const target = e.target as HTMLImageElement;
+                if (target.src !== PLACEHOLDER_IMAGE_URL) {
+                    target.src = PLACEHOLDER_IMAGE_URL;
+                    // Clear srcSet to prevent fallback to other sizes that might also fail
+                    target.srcset = '';
+                }
+            }}
+            sizes={generateThumbnailSizesAttribute()}
+            src={getThumbnailSrc(baseUrl)}
+            srcSet={generateThumbnailSrcSet(baseUrl)}
+            title={title}
+        />
+    );
+};

package/src/ImageSlider/components/ResponsiveImage/index.ts

@@ -0,0 +1 @@
+export { ResponsiveImage } from './ResponsiveImage';

package/src/ImageSlider/components/Thumbnails/Thumbnails.tsx

@@ -0,0 +1,184 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { PLACEHOLDER_IMAGE_URL, THUMBNAIL } from '../../constants';
+import { ImageSliderCard, ResponsiveImageData } from '../../ImageSlider.types';
+
+/**
+ * Props for the Thumbnails component
+ */
+type Props = {
+    /** Array of image cards to display as thumbnails */
+    cards: ImageSliderCard[];
+    /** Currently active page number (1-based) */
+    currentPage: number;
+    /** Function to generate responsive thumbnail sizes attribute */
+    generateThumbnailSizesAttribute: () => string;
+    /** Function to generate responsive thumbnail srcSet */
+    generateThumbnailSrcSet: (baseUrl: string) => string;
+    /** Callback fired when a thumbnail is clicked */
+    onThumbnailClick: (pageNumber: number) => void;
+    /** Orientation of the thumbnail previews */
+    orientation: 'vertical' | 'horizontal';
+};
+
+/**
+ * Thumbnails component displays clickable thumbnail previews for image navigation.
+ * Supports both vertical and horizontal orientations with consistent 111px sizing across all viewports.
+ */
+export const Thumbnails = ({
+    cards,
+    currentPage,
+    generateThumbnailSizesAttribute,
+    generateThumbnailSrcSet,
+    onThumbnailClick,
+    orientation,
+}: Props) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const thumbnailRefs = useRef<(HTMLButtonElement | null)[]>([]);
+    const previousPageRef = useRef<number>(currentPage);
+
+    // Initialize refs array to match cards length - more efficient approach
+    useEffect(() => {
+        // Only resize if length changed, don't create new array unnecessarily
+        if (thumbnailRefs.current.length !== cards.length) {
+            thumbnailRefs.current.length = cards.length;
+        }
+    }, [cards.length]);
+
+    // Helper function to modify baseUrl query parameters for quality and sharpening
+    // Memoized to avoid repeated URL object creation
+    const enhanceBaseUrl = useCallback((baseUrl: string) => {
+        // Use string manipulation instead of URL constructor for better performance
+        const hasParams = baseUrl.includes('?');
+        const separator = hasParams ? '&' : '?';
+        return `${baseUrl}${separator}quality=${THUMBNAIL.QUALITY}&sharpen=false`;
+    }, []);
+
+    // Helper function to render thumbnail images with low fetch priority
+    const renderThumbnailImage = useCallback(
+        (imageData: ResponsiveImageData, index: number, thumbnailSize: number) => {
+            const { alt, baseUrl, title } = imageData;
+            const enhancedBaseUrl = enhanceBaseUrl(baseUrl);
+            return (
+                <img
+                    alt={alt}
+                    className={`h-full max-h-[${thumbnailSize}px] w-full max-w-[${thumbnailSize}px] bg-background-primary object-contain`}
+                    fetchPriority={index <= 5 ? 'high' : 'low'}
+                    loading={index <= 5 ? 'eager' : 'lazy'}
+                    onError={(e) => {
+                        const target = e.target as HTMLImageElement;
+                        if (target.src !== PLACEHOLDER_IMAGE_URL) {
+                            target.src = PLACEHOLDER_IMAGE_URL;
+                            // Clear srcSet to prevent fallback to other sizes that might also fail
+                            target.srcset = '';
+                        }
+                    }}
+                    sizes={generateThumbnailSizesAttribute()}
+                    src={`${enhancedBaseUrl}&width=${thumbnailSize}`} // Fallback for browsers without srcSet support
+                    srcSet={generateThumbnailSrcSet(enhancedBaseUrl)}
+                    title={title}
+                />
+            );
+        },
+        [generateThumbnailSrcSet, generateThumbnailSizesAttribute, enhanceBaseUrl]
+    );
+
+    // Auto-scroll the active thumbnail into view when currentPage changes
+    // Only scroll if the page actually changed (not on mount or remount from mobile → desktop)
+    useEffect(() => {
+        const pageChanged = previousPageRef.current !== currentPage;
+
+        // Update the ref for next comparison
+        previousPageRef.current = currentPage;
+
+        // Only scroll if the page actually changed
+        if (!pageChanged) {
+            return;
+        }
+
+        const activeIndex = currentPage - 1;
+        const activeThumbnail = thumbnailRefs.current[activeIndex];
+
+        if (activeThumbnail && containerRef.current) {
+            activeThumbnail.scrollIntoView({
+                behavior: 'smooth',
+                block: 'nearest',
+                inline: 'center',
+            });
+        }
+    }, [currentPage, orientation]);
+
+    /**
+     * Creates thumbnail preview images that can be clicked to navigate to specific images.
+     * Supports both horizontal and vertical orientations with configurable size and dimming.
+     * Supports both custom ReactNode cards and responsive imageData.
+     */
+    const thumbnailPreviews = useMemo(() => {
+        const isHorizontal = orientation === 'horizontal';
+        const thumbnailSize = isHorizontal ? 48 : THUMBNAIL.SIZE;
+
+        return cards.map(({ card, imageData, key }, index) => {
+            const pageNumber = index + 1;
+            const isActive = currentPage === pageNumber;
+
+            return (
+                <button
+                    aria-current={isActive ? 'true' : 'false'}
+                    aria-label={`Go to image ${pageNumber}${imageData?.alt ? `: ${imageData.alt}` : ''}`}
+                    aria-selected={isActive}
+                    className={cn(
+                        'box-border flex-shrink-0 cursor-pointer overflow-hidden rounded-md transition-all duration-100',
+                        'hui-focus-visible-outline hover:opacity-80 focus:-outline-offset-4',
+                        `aspect-square h-[${thumbnailSize}px] w-[${thumbnailSize}px] max-h-[${thumbnailSize}px] max-w-[${thumbnailSize}px]`,
+                        // Use outline instead of border to avoid affecting box dimensions
+                        isActive
+                            ? 'opacity-100 outline outline-2 -outline-offset-2 outline-border-selected'
+                            : 'opacity-50 outline outline-1 -outline-offset-1 outline-border-secondary'
+                    )}
+                    data-active={isActive}
+                    data-page={pageNumber}
+                    key={key}
+                    onClick={() => onThumbnailClick(pageNumber)}
+                    ref={(el) => {
+                        thumbnailRefs.current[index] = el;
+                    }}
+                    role="tab"
+                    style={{
+                        height: `${thumbnailSize}px`,
+                        maxHeight: `${thumbnailSize}px`,
+                        maxWidth: `${thumbnailSize}px`,
+                        width: `${thumbnailSize}px`,
+                    }}
+                    type="button"
+                >
+                    <div className="h-full w-full bg-background-primary">
+                        {/* Render responsive image if imageData is provided, otherwise use custom card */}
+                        {imageData ? renderThumbnailImage(imageData, index, thumbnailSize) : card}
+                    </div>
+                </button>
+            );
+        });
+    }, [cards, currentPage, onThumbnailClick, renderThumbnailImage, orientation]);
+
+    const isHorizontal = orientation === 'horizontal';
+
+    return (
+        <div
+            aria-label="Image thumbnails"
+            className={cn(
+                'flex xsMax:hidden',
+                isHorizontal
+                    ? 'w-full flex-row justify-center overflow-x-auto overflow-y-hidden pb-2xs'
+                    : 'h-full w-[136px] flex-col overflow-y-auto overflow-x-hidden pr-2xs mdMax:w-[128px]'
+            )}
+            ref={containerRef}
+            role="tablist"
+            style={{
+                scrollbarWidth: 'thin',
+            }}
+        >
+            <div className={cn('flex gap-xs', isHorizontal ? 'flex-row' : 'flex-col')}>{thumbnailPreviews}</div>
+        </div>
+    );
+};

package/src/ImageSlider/constants.ts

@@ -0,0 +1,59 @@
+import { spacing } from '@evolve.ui/theme-system/themes/common';
+
+import placeholderImage from './assets/placeholder.svg';
+import { ImageSliderCard } from './ImageSlider.types';
+
+/**
+ * Constants used throughout the ImageSlider component
+ */
+
+// Breakpoints
+export const MOBILE_BREAKPOINT = 768;
+export const MOBILE_BREAKPOINT_QUERY = `(max-width: ${MOBILE_BREAKPOINT}px)`;
+
+// Spacing values (use design tokens)
+export const SPACING = {
+    GAP_2XS: spacing.xxsValue, // gap-2xs (4px)
+    GAP_MD: spacing.mdValue, // gap-md (24px)
+    MARGIN_SM: spacing.smValue, // ml-sm, mr-sm (16px)
+} as const;
+
+// Thumbnail dimensions
+export const THUMBNAIL = {
+    QUALITY: 50, // Thumbnail quality setting
+    SIZE: 111, // Fixed thumbnail size
+    WIDTH_PARAM: 107, // URL width parameter for thumbnails
+} as const;
+
+// Mobile card dimensions
+export const MOBILE_CARD = {
+    MAX_WIDTH: 651, // Max card width
+    WIDTH_REDUCTION: 64, // calc(100% - 64px) to match container extension for optimal bleed effect
+} as const;
+
+// Animation timings
+export const ANIMATION = {
+    DEBOUNCE_DELAY: 100, // Scroll handler debounce delay
+    SCROLL_TIMEOUT: 300, // Smooth scroll animation duration
+} as const;
+
+// Navigation button positioning
+export const NAVIGATION = {
+    INSIDE_TOP_OFFSET: 21, // top-[calc(50%-21px)]
+    OUTSIDE_TOP_OFFSET: 17, // top-[calc(50%-17px)]
+} as const;
+
+// Bundled brand-neutral fallback (inlined as a data URI at build time) — the image-error
+// fallback must never depend on an external CDN.
+export const PLACEHOLDER_IMAGE_URL = placeholderImage;
+
+export const PLACEHOLDER_EMPTY_CARDS: ImageSliderCard[] = [
+    {
+        imageData: {
+            alt: 'Placeholder empty card',
+            baseUrl: PLACEHOLDER_IMAGE_URL,
+            title: 'Placeholder empty card',
+        },
+        key: 'placeholder-empty-card-1',
+    },
+];

package/src/ImageSlider/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useImageSlider } from './useImageSlider';
+export { useImageSliderNavigation } from './useImageSliderNavigation';
+export { useImageSliderScrollHandler } from './useImageSliderScrollHandler';

package/src/ImageSlider/hooks/useImageSlider.ts

@@ -0,0 +1,57 @@
+import { useRef, useState } from 'react';
+
+import { useWindowIsMobile } from '../../providers';
+import { ResponsiveImageConfig } from '../ImageSlider.types';
+
+/**
+ * Props for the useImageSlider hook
+ */
+type UseImageSliderProps = {
+    /** Number of cards/images in the slider */
+    numberOfPages: number;
+    /** Responsive image configuration */
+    responsiveImageConfig: ResponsiveImageConfig;
+};
+
+/**
+ * Main hook for ImageSlider component that provides basic state and refs
+ * Navigation and scroll handling are managed separately to avoid circular dependencies
+ * @param props - ImageSlider configuration
+ * @returns Basic state and handlers needed for the ImageSlider component
+ */
+export const useImageSlider = ({ numberOfPages, responsiveImageConfig }: UseImageSliderProps) => {
+    const containerRef = useRef<HTMLDivElement | null>(null);
+    const contentRef = useRef<HTMLDivElement | null>(null);
+
+    const [hasHoveredGallery, setHasHoveredGallery] = useState(false);
+    const isMobile = useWindowIsMobile();
+
+    const handleMouseOver = () => {
+        if (!isMobile && !hasHoveredGallery) {
+            setHasHoveredGallery(true);
+        }
+    };
+
+    const handleMobileInteraction = () => {
+        if (isMobile && !hasHoveredGallery) {
+            setHasHoveredGallery(true);
+        }
+    };
+
+    return {
+        // Refs
+        containerRef,
+        contentRef,
+
+        // Event handlers
+        handleMobileInteraction,
+        handleMouseOver,
+
+        // State
+        hasHoveredGallery,
+        isMobile,
+        numberOfPages,
+        responsiveImageConfig,
+        setHasHoveredGallery,
+    };
+};