@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/ImageSlider/hooks/useImageSliderNavigation.ts

@@ -0,0 +1,133 @@
+import { RefObject, useCallback, useEffect, useState } from 'react';
+
+import { ImageSliderCard, ThumbnailDisplay } from '../ImageSlider.types';
+
+/**
+ * Props for the useImageSliderNavigation hook
+ */
+type UseImageSliderNavigationProps = {
+    /** The cards in the slider */
+    cards: ImageSliderCard[];
+    /** Optional key to identify when content has changed (e.g., an item id) */
+    contentKey?: string | number;
+    /** Ref to the content container */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** Whether the slider is currently scrolling */
+    isScrolling: boolean;
+    /** Total number of pages/slides */
+    numberOfPages: number;
+    /** Function to reset the gallery hover state when content changes (new URL/different images) */
+    setHasHoveredGallery: (hasHovered: boolean) => void;
+    /** Display mode for navigation controls; 'index' uses same button visibility as horizontal */
+    thumbnailDisplay?: ThumbnailDisplay;
+    /** Orientation of the thumbnail previews */
+    thumbnailOrientation?: 'vertical' | 'horizontal';
+};
+
+/**
+ * Hook for managing navigation state and handlers in the ImageSlider.
+ * Implements wraparound navigation where clicking previous on the first image
+ * jumps to the last image, and clicking next on the last image jumps to the first.
+ * @param props - Navigation configuration
+ * @returns Navigation state and handlers
+ */
+export const useImageSliderNavigation = ({
+    contentKey,
+    contentRef,
+    isScrolling,
+    numberOfPages,
+    setHasHoveredGallery,
+    thumbnailDisplay = ThumbnailDisplay.Thumbnails,
+    thumbnailOrientation = 'vertical',
+}: UseImageSliderNavigationProps) => {
+    const [currentPage, setCurrentPage] = useState(1);
+
+    // For horizontal thumbnails or index display, always show buttons even with single image
+    // For vertical thumbnails, hide buttons when there's only one image
+    const showNavButtonsWithSingleImage =
+        thumbnailOrientation === 'horizontal' || thumbnailDisplay === ThumbnailDisplay.Index;
+    const showPreviousPageButton = showNavButtonsWithSingleImage ? true : numberOfPages > 1;
+    const showNextPageButton = showNavButtonsWithSingleImage ? true : numberOfPages > 1;
+
+    // For horizontal/index with single image, disable buttons
+    // For vertical or multiple images, use wraparound navigation (never disabled)
+    const isPreviousPageDisabled = showNavButtonsWithSingleImage && numberOfPages <= 1;
+    const isNextPageDisabled = showNavButtonsWithSingleImage && numberOfPages <= 1;
+
+    const goToPreviousPage = useCallback(() => {
+        if (!isScrolling) {
+            // Trigger hover state to load all images when navigation is used
+            setHasHoveredGallery(true);
+            if (currentPage > 1) {
+                setCurrentPage(currentPage - 1);
+            } else {
+                // Wrap to last page when on first page
+                setCurrentPage(numberOfPages);
+            }
+        }
+    }, [currentPage, numberOfPages, isScrolling, setCurrentPage, setHasHoveredGallery]);
+
+    const goToNextPage = useCallback(() => {
+        if (!isScrolling) {
+            // Trigger hover state to load all images when navigation is used
+            setHasHoveredGallery(true);
+            if (currentPage < numberOfPages) {
+                setCurrentPage(currentPage + 1);
+            } else {
+                // Wrap to first page when on last page
+                setCurrentPage(1);
+            }
+        }
+    }, [currentPage, numberOfPages, isScrolling, setCurrentPage, setHasHoveredGallery]);
+
+    const handleThumbnailClick = useCallback(
+        (pageNumber: number) => {
+            if (!isScrolling) {
+                // Trigger hover state to load all images when thumbnail navigation is used
+                setHasHoveredGallery(true);
+                setCurrentPage(pageNumber);
+            }
+        },
+        [isScrolling, setCurrentPage, setHasHoveredGallery]
+    );
+
+    /**
+     * Handles keyboard navigation for the slider.
+     * Allows using Left and Right arrow keys to navigate between images.
+     */
+    const onKeyNavigation = useCallback(
+        (event: React.KeyboardEvent) => {
+            if (event.key === 'ArrowRight') {
+                goToNextPage();
+            } else if (event.key === 'ArrowLeft') {
+                goToPreviousPage();
+            }
+        },
+        [goToNextPage, goToPreviousPage]
+    );
+
+    useEffect(() => {
+        setCurrentPage(1);
+        // Reset hover state when content changes (new content key/different images)
+        setHasHoveredGallery(false);
+        if (contentRef.current && typeof contentRef.current.scrollTo === 'function') {
+            contentRef.current.scrollTo({
+                behavior: 'instant',
+                left: 0,
+            });
+        }
+    }, [contentKey, contentRef, setHasHoveredGallery]);
+
+    return {
+        currentPage,
+        goToNextPage,
+        goToPreviousPage,
+        handleThumbnailClick,
+        isNextPageDisabled,
+        isPreviousPageDisabled,
+        onKeyNavigation,
+        setCurrentPage,
+        showNextPageButton,
+        showPreviousPageButton,
+    };
+};

package/src/ImageSlider/hooks/useImageSliderScrollHandler.ts

@@ -0,0 +1,171 @@
+import { debounce } from 'es-toolkit';
+import { RefObject, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useWindowIsMobile } from '../../providers';
+import { ANIMATION, MOBILE_CARD, SPACING } from '../constants';
+
+/**
+ * Props for the useImageSliderScrollHandler hook
+ */
+type UseImageSliderScrollHandlerProps = {
+    /** Ref to the content container */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** Current page number */
+    currentPage: number;
+    /**
+     * Max width in px of each carousel card on mobile (matches `responsiveImageConfig.desktopSize` on the slider).
+     * @default MOBILE_CARD.MAX_WIDTH
+     */
+    maxMobileCardWidth?: number;
+    /** Total number of pages */
+    numberOfPages: number;
+    /** Function to update the current page */
+    setCurrentPage: (page: number) => void;
+    /** Function to update the scrolling state */
+    setIsScrolling?: (isScrolling: boolean) => void;
+};
+
+/**
+ * Hook for managing scroll behavior and page tracking in the ImageSlider
+ * @param props - Scroll handler configuration
+ * @returns Scroll handlers and scrolling state
+ */
+export const useImageSliderScrollHandler = ({
+    contentRef,
+    currentPage,
+    maxMobileCardWidth = MOBILE_CARD.MAX_WIDTH,
+    numberOfPages,
+    setCurrentPage,
+    setIsScrolling,
+}: UseImageSliderScrollHandlerProps) => {
+    const [internalIsScrolling, setInternalIsScrolling] = useState(false);
+    const isScrollingState = setIsScrolling ? internalIsScrolling : false;
+    const isMobile = useWindowIsMobile();
+    const previousPageRef = useRef<number>(currentPage);
+
+    // Handle programmatic scrolling on page changes (desktop only)
+    useEffect(() => {
+        if (contentRef.current) {
+            // Skip programmatic scrolling on mobile - let natural snap scrolling handle it
+            if (isMobile) {
+                return;
+            }
+
+            const pageChanged = previousPageRef.current !== currentPage;
+
+            // Set scrolling state to prevent rapid navigation
+            if (setIsScrolling) {
+                setIsScrolling(true);
+            } else {
+                setInternalIsScrolling(true);
+            }
+
+            // Calculate scroll position including gap for desktop
+            const containerWidth = contentRef.current.offsetWidth;
+            const gap = SPACING.GAP_MD; // md gap in pixels for desktop
+            const scrollPosition = (currentPage - 1) * (containerWidth + gap);
+
+            // Use 'auto' (instant) instead of 'smooth' if page hasn't changed
+            // This prevents page scrolling on resize/mount while keeping smooth scrolling for navigation
+            contentRef.current.scrollTo({
+                behavior: pageChanged ? 'smooth' : 'auto',
+                left: scrollPosition,
+            });
+
+            // Reset scrolling state after animation completes
+            // Smooth scroll animation typically takes ~300-400ms
+            const scrollTimeout = setTimeout(() => {
+                if (setIsScrolling) {
+                    setIsScrolling(false);
+                } else {
+                    setInternalIsScrolling(false);
+                }
+            }, ANIMATION.SCROLL_TIMEOUT);
+
+            // Update previous page reference
+            previousPageRef.current = currentPage;
+
+            return () => {
+                clearTimeout(scrollTimeout);
+            };
+        }
+        return undefined;
+    }, [currentPage, contentRef, setIsScrolling, isMobile]);
+
+    /**
+     * Memoized debounced scroll handler for desktop scroll tracking.
+     * Updates the current page when user scrolls to reflect active thumbnail.
+     */
+    const debouncedDesktopScrollHandler = useMemo(
+        () =>
+            debounce(() => {
+                if (contentRef.current && !isMobile) {
+                    const scrollLeft = contentRef.current.scrollLeft;
+                    const containerWidth = contentRef.current.offsetWidth;
+                    const gap = SPACING.GAP_MD; // md gap in pixels for desktop
+                    const newPage = Math.round(scrollLeft / (containerWidth + gap)) + 1;
+
+                    if (newPage !== currentPage && newPage >= 1 && newPage <= numberOfPages) {
+                        setCurrentPage(newPage);
+                    }
+                }
+            }, ANIMATION.DEBOUNCE_DELAY),
+        [currentPage, numberOfPages, contentRef, setCurrentPage, isMobile]
+    );
+
+    /**
+     * Memoized debounced scroll handler for mobile scroll tracking.
+     * Updates the current page based on mobile card layout with gaps and margins.
+     */
+    const debouncedMobileScrollHandler = useMemo(
+        () =>
+            debounce(() => {
+                if (contentRef.current && isMobile) {
+                    const { clientWidth, scrollLeft, scrollWidth } = contentRef.current;
+                    const maxScroll = scrollWidth - clientWidth;
+
+                    // Prevent scrolling beyond bounds
+                    if (scrollLeft < 0) {
+                        contentRef.current.scrollLeft = 0;
+                    } else if (scrollLeft > maxScroll) {
+                        contentRef.current.scrollLeft = maxScroll;
+                    }
+
+                    // Calculate current page based on scroll position
+                    // Mobile cards: min(calc(100% - 64px), maxMobileCardWidth) with 4px gaps
+                    // First card has 16px left margin, last card has 16px right margin
+                    const gap = SPACING.GAP_2XS;
+                    const margin = SPACING.MARGIN_SM;
+                    const cardWidth = Math.min(clientWidth - MOBILE_CARD.WIDTH_REDUCTION, maxMobileCardWidth);
+                    const cardWithGap = cardWidth + gap;
+
+                    // Calculate which card is most visible based on scroll position
+                    // Account for the initial margin offset
+                    const adjustedScrollLeft = scrollLeft + margin;
+                    const newPage = Math.round(adjustedScrollLeft / cardWithGap) + 1;
+
+                    if (newPage !== currentPage && newPage >= 1 && newPage <= numberOfPages) {
+                        setCurrentPage(newPage);
+                    }
+                }
+            }, ANIMATION.DEBOUNCE_DELAY),
+        [currentPage, maxMobileCardWidth, numberOfPages, contentRef, setCurrentPage, isMobile]
+    );
+
+    /**
+     * Handles scroll events within the slider content area.
+     * Uses debounced handlers for both mobile and desktop to improve performance.
+     */
+    const onScrollCards = useCallback(() => {
+        if (isMobile) {
+            debouncedMobileScrollHandler();
+        } else {
+            debouncedDesktopScrollHandler();
+        }
+    }, [isMobile, debouncedMobileScrollHandler, debouncedDesktopScrollHandler]);
+
+    return {
+        isScrolling: isScrollingState,
+        onScrollCards,
+    };
+};

package/src/ImageSlider/index.ts

@@ -0,0 +1,3 @@
+export * from './ImageSlider';
+export * from './ImageSlider.types';
+export * from './components/Thumbnails/Thumbnails';

package/src/ImageSlider/utils/imageOptimization.ts

@@ -0,0 +1,97 @@
+import { THUMBNAIL } from '../constants';
+import { ResponsiveImageConfig } from '../ImageSlider.types';
+
+/**
+ * Generates a srcSet string for main images with responsive breakpoints
+ * @param baseUrl - The base URL of the image
+ * @param config - Responsive image configuration
+ * @param useHighQuality - Whether to use high quality mode (no width constraints)
+ * @returns The srcSet string for the image
+ */
+export const generateMainImageSrcSet = (
+    baseUrl: string,
+    config: ResponsiveImageConfig,
+    useHighQuality: boolean = false
+): string => {
+    // If high quality mode is enabled (after hover), return empty string
+    // This forces the browser to use only the src attribute (full quality)
+    // avoiding intermediate 651px requests
+    if (useHighQuality) {
+        return '';
+    }
+
+    const { desktopSize, mobileSize } = config;
+    const widths = [mobileSize, desktopSize];
+
+    return widths
+        .map((width) => {
+            return `${baseUrl}&width=${width} ${width}w`;
+        })
+        .join(', ');
+};
+
+/**
+ * Generates a srcSet string for thumbnail images
+ * @param baseUrl - The base URL of the image
+ * @returns The srcSet string for the thumbnail
+ */
+export const generateThumbnailSrcSet = (baseUrl: string): string => {
+    return `${baseUrl}&width=${THUMBNAIL.WIDTH_PARAM} ${THUMBNAIL.WIDTH_PARAM}w`;
+};
+
+/**
+ * Generates the sizes attribute for responsive images
+ * @param config - Responsive image configuration
+ * @param useHighQuality - Whether to use high quality mode
+ * @returns The sizes attribute string
+ */
+export const generateSizesAttribute = (config: ResponsiveImageConfig, useHighQuality: boolean = false): string => {
+    // If high quality mode is enabled (after hover), sizes attribute is not needed
+    // since we're using empty srcSet and relying only on src attribute
+    if (useHighQuality) {
+        return '';
+    }
+
+    const { breakpoint, desktopSize, mobileSize } = config;
+    // Use a much smaller size on mobile to force selection of 366w image even on high-DPR devices
+    const adjustedMobileSize = Math.floor(mobileSize / 3); // ~122px, ensuring 366w is selected even at DPR 3.0
+    return `(max-width: ${breakpoint}px) ${adjustedMobileSize}px, ${desktopSize}px`;
+};
+
+// Memoized thumbnail sizes attribute (static value)
+const THUMBNAIL_SIZES_ATTRIBUTE = `${THUMBNAIL.WIDTH_PARAM}px`;
+
+/**
+ * Generates the sizes attribute for thumbnail images
+ * @returns The sizes attribute string for thumbnails
+ */
+export const generateThumbnailSizesAttribute = (): string => {
+    return THUMBNAIL_SIZES_ATTRIBUTE;
+};
+
+/**
+ * Gets the appropriate image source URL based on quality mode
+ * @param baseUrl - The base URL of the image
+ * @param config - Responsive image configuration
+ * @param useHighQuality - Whether to use high quality mode
+ * @returns The appropriate source URL
+ */
+export const getImageSrc = (
+    baseUrl: string,
+    config: ResponsiveImageConfig,
+    useHighQuality: boolean = false
+): string => {
+    if (useHighQuality) {
+        return baseUrl;
+    }
+    return `${baseUrl}&width=${config.mobileSize}`;
+};
+
+/**
+ * Gets the thumbnail image source URL
+ * @param baseUrl - The base URL of the image
+ * @returns The thumbnail source URL
+ */
+export const getThumbnailSrc = (baseUrl: string): string => {
+    return `${baseUrl}&width=${THUMBNAIL.WIDTH_PARAM}`;
+};

package/src/ImageSlider/utils/index.ts

@@ -0,0 +1 @@
+export * from './imageOptimization';

package/src/InlineNotification/InlineNotification.tsx

@@ -0,0 +1,95 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ComponentProps, ReactNode } from 'react';
+
+import { CheckCircle, Info, Warning } from '../Icons';
+import { BodyPrimary, BodySecondary } from '../Typography/Text/Text';
+
+type Props = {
+    className?: string;
+    level: 'success' | 'info' | 'critical' | 'warning';
+    message: string | ReactNode;
+    small?: boolean;
+};
+
+export const InlineNotification = ({ className, level, message, small = false }: Props) => {
+    let icon: ReactNode;
+    let messageColor: ComponentProps<typeof BodySecondary>['color'];
+    switch (level) {
+        case 'success':
+            icon = small ? (
+                <CheckCircle
+                    color="success"
+                    size="sm"
+                    style="fill"
+                />
+            ) : (
+                <CheckCircle
+                    color="success"
+                    size="md"
+                    style="fill"
+                />
+            );
+            messageColor = 'success';
+            break;
+        case 'critical':
+            icon = small ? (
+                <Warning
+                    color="critical"
+                    size="sm"
+                    style="fill"
+                />
+            ) : (
+                <Warning
+                    color="critical"
+                    size="md"
+                    style="fill"
+                />
+            );
+            messageColor = 'critical';
+            break;
+        case 'warning':
+            icon = small ? (
+                <Warning
+                    color="warning"
+                    size="sm"
+                    style="fill"
+                />
+            ) : (
+                <Warning
+                    color="warning"
+                    size="md"
+                    style="fill"
+                />
+            );
+            messageColor = 'primary';
+            break;
+        case 'info':
+        default:
+            icon = small ? (
+                <Info
+                    color="info"
+                    size="sm"
+                    style="fill"
+                />
+            ) : (
+                <Info
+                    color="info"
+                    size="md"
+                    style="fill"
+                />
+            );
+            messageColor = 'primary';
+            break;
+    }
+
+    return (
+        <div className={cn('flex items-center', className)}>
+            <div className="mr-xs">{icon}</div>
+            {small ? (
+                <BodySecondary color={messageColor}>{message}</BodySecondary>
+            ) : (
+                <BodyPrimary color={messageColor}>{message}</BodyPrimary>
+            )}
+        </div>
+    );
+};