@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Carousel/Carousel.tsx

@@ -0,0 +1,513 @@
+import { cn } from '@evolve.ui/theme-system';
+import { debounce } from 'es-toolkit';
+import {
+    KeyboardEventHandler,
+    MouseEvent,
+    ReactNode,
+    UIEventHandler,
+    useCallback,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+import useMeasure from 'react-use-measure';
+
+import { CaretRight } from '../Icons';
+import { useWindowIsDesktop } from '../providers';
+import { SubtleLink } from '../Typography/Links/Links';
+import {
+    CAROUSEL_CARD_GAP_MOBILE_NUM,
+    CAROUSEL_CARD_GAP_NUM,
+    CarouselCard,
+    CarouselGoToPageDirection,
+    CarouselGoToPageInfo,
+    CarouselPageInfo,
+} from './Carousel.types';
+import { calculatePageBreakpoints } from './Carousel.utils';
+import { DotButton } from './components/DotButton/DotButton';
+import { NavigationButtons } from './components/NavigationButtons/NavigationButtons';
+import { TitleSection } from './components/TitleSection/TitleSection';
+
+const SCROLL_DEBOUNCE_TIME = 50;
+
+type Props = {
+    /**
+     * A Link element that a user can interact with.
+     * Usually, this will be something like a "View all" that links to a page with all the items that the carousel represents.
+     *
+     * It will appear on the right side, opposite of the title, if one exists
+     *
+     * @property {string} path - Where the user will be taken upon clicking the action
+     * @property {string} text="View All" - The text to be displayed in the action element
+     */
+    action?: {
+        hideIcon?: boolean;
+        onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+        /**
+         * Where the user will be taken upon clicking the action
+         */
+        path: string;
+        /**
+         * The text to be displayed in the action element
+         *
+         * @default "View All"
+         */
+        text?: string;
+    };
+    /**
+     * If provided, the cards, barring the first card, will be offset so that some of the previous card will be shown on the left.
+     * This is best used for mobile carousels so that people can better see that they're in the middle of a carousel.
+     * It should be a positive number, representing a pixel amount.
+     * Gap size will be added to it, so make sure you aren't including it.
+     *
+     * @default 0
+     */
+    cardOffset?: number;
+    /**
+     * The scrollable content of the carousel.
+     * Should be individual elements, likes cards or images.
+     *
+     * @property {ReactNode} card - The rendered content
+     * @property {string} key - A unique identifier for the card
+     */
+    cards: CarouselCard[];
+    /**
+     * Are the cards taking up a full page of the carousel?
+     * This is used to use card counts to render the page-based sections of the carousel for SSR.
+     */
+    fullPage?: boolean;
+    /**
+     * Bring the slider to the selected page. Only one property will be defined, so components using this function should check
+     * which one is populated.
+     *
+     * @property {CarouselGoToPageDirection} buttonDirection - If populated, refers to which button was pressed: Previous or Next
+     * @property {number} oneBasedPageNumber - If populated, refers to which page the user is specifically going to
+     *
+     * @see CarouselGoToPageInfo
+     */
+    goToPage?: (goToPageInfo: CarouselGoToPageInfo) => void;
+    /**
+     * Callback triggered when the user scrolls through the carousel manually (either through mouse wheel or dragging)
+     */
+    onScroll?: (currentScrollPage: number) => void;
+    /**
+     * @returns The number of pages for the carousel
+     */
+    providePageCount?: (numberOfPages: number) => void;
+    /**
+     * The selected page to scroll to directly
+     */
+    selectedPage?: number;
+    /**
+     * If the user scrolls, they're automatically brought to a specific page breakpoint.
+     * Set this to `false` to avoid further scrolling after the user has stopped scrolling through the carousel.
+     *
+     * @default true
+     */
+    shouldGoToPageBreakpointsOnScrolling?: boolean;
+    /**
+     * Displays dots at the bottom of the carousel that represent a page of content.
+     * Clicking a dot will bring the user to the corresponding page.
+     * Mobile devices will NEVER show the page selector.
+     *
+     * @default false
+     */
+    showPagination?: boolean;
+    subHeaderDescription?: string;
+    /**
+     * Left side content for the carousel subheader - can be either a link or plain text.
+     */
+    subHeaderLeft?:
+        | {
+              link: {
+                  ariaLabel?: string;
+                  href: string;
+                  label: string;
+                  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+                  variant?: 'default' | 'subtle';
+              };
+              type: 'link';
+          }
+        | { text: string; type: 'text' };
+    /**
+     * The title of the carousel, display above and to the left of the carousel.
+     * Even though it's a ReactNode, this is for formatMessage/other intl-based libraries
+     * to pass in populated values. You should pass in a value that is string-based, due
+     * to the carousel variant formatting the title as an h2 or h5.
+     *
+     * Optional.
+     *
+     * @variation primary - If carousel is primary, title is rendered as an H2
+     * @variation secondary - If carousel is secondary, title is rendered as an H5
+     *
+     * @see {variant}
+     */
+    title?: ReactNode;
+    /**
+     * Link configuration for the title - when provided, title becomes clickable with hover underline
+     */
+    titleLink?: {
+        /** Accessible label for the title link */
+        ariaLabel?: string;
+        /** URL for the title link */
+        href: string;
+        /** Click handler for the title link */
+        onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    };
+    /**
+     * If true, the carousel will use overlay controls to navigate to the next and previous pages.
+     *
+     * @default false
+     */
+    useOverlayControls?: boolean;
+    /**
+     * @variation {primary} - A primary carousel displays important content relevant to the page. Should only have one per page.
+     * @variation {secondary} - A secondary carousel display content of lesser importance to the user. Can have multiple per page.
+     *
+     * @default primary
+     */
+    variant?: 'primary' | 'secondary';
+};
+
+/**
+ * Displays a scrollable list of cards or elements horizontally.
+ * Allows navigation via buttons, dots (pagination), or touch gestures (on mobile).
+ */
+export const Carousel = ({
+    action,
+    cardOffset = 0,
+    cards,
+    fullPage = false,
+    goToPage,
+    onScroll,
+    providePageCount,
+    selectedPage,
+    shouldGoToPageBreakpointsOnScrolling = true,
+    showPagination = false,
+    subHeaderDescription,
+    subHeaderLeft,
+    title,
+    titleLink,
+    useOverlayControls,
+    variant = 'primary',
+}: Props) => {
+    const isDesktop = useWindowIsDesktop();
+    const [containerRef, { width }] = useMeasure();
+    const contentRef = useRef<HTMLDivElement>(null);
+
+    const actionElement = useMemo(() => {
+        if (action) {
+            const { hideIcon = false, onClick, path, text = 'View All' } = action;
+
+            return (
+                <SubtleLink
+                    className="flex items-center gap-2xs"
+                    href={path}
+                    onClick={onClick}
+                >
+                    {text} {!hideIcon && <CaretRight size="sm" />}
+                </SubtleLink>
+            );
+        }
+        return undefined;
+    }, [action]);
+
+    const [currentPage, setCurrentPage] = useState(1);
+    const [shouldGoToPageBreakpoint, setShouldGoToPageBreakpoint] = useState(false);
+    // Prevents onScroll prop from firing during programmatic scrollTo (e.g. AutomatedCarousel autoplay),
+    // which would otherwise pause autoplay by triggering the parent's scroll handler.
+    const isProgrammaticScroll = useRef(false);
+    const cardRefs = useRef<(HTMLDivElement | null)[]>([]);
+    const [pageInfo, setPageInfo] = useState<CarouselPageInfo>({
+        breakpoints: [0],
+        cardsPerPage: 0,
+        numberOfPages: 1,
+    });
+
+    /**
+     * Ensure the ref array has the correct size when the number of cards changes.
+     */
+    useEffect(() => {
+        cardRefs.current = cardRefs.current.slice(0, cards.length);
+    }, [cards.length]);
+
+    /**
+     * These cards are wrapped in a div.
+     * The div is guaranteed to have a unique key.
+     * The div also has a ref used to control the scrolling animation.
+     */
+    const carouselCards = useMemo(() => {
+        return cards.map(({ card, key }, index) => (
+            <div
+                className={cn('backface-hidden transform-gpu will-change-transform xsMax:shrink-0', {
+                    'xsMax:pl-sm': index === 0,
+                    'xsMax:pr-sm': index === cards.length - 1,
+                })}
+                key={key}
+                ref={(el) => {
+                    // Directly assign the element or null to the ref array at the correct index
+                    cardRefs.current[index] = el;
+                }}
+                role="listitem"
+            >
+                {card}
+            </div>
+        ));
+    }, [cards]);
+
+    useEffect(() => {
+        const allRefsPopulated =
+            cardRefs.current.length === cards.length && cardRefs.current.every((ref) => ref !== null);
+
+        if (cards.length > 0 && contentRef.current && allRefsPopulated) {
+            const gap = isDesktop ? CAROUSEL_CARD_GAP_NUM : CAROUSEL_CARD_GAP_MOBILE_NUM;
+            let contentTotalWidth = 0;
+
+            const cumulativeWidths = cards.map((_, index) => {
+                const ref = cardRefs.current[index];
+                if (!ref) {
+                    return contentTotalWidth;
+                }
+                const isLastCard = index === cards.length - 1;
+                contentTotalWidth += ref.offsetWidth + (isLastCard ? 0 : gap);
+                return contentTotalWidth;
+            });
+
+            const scrollAreaWidth = contentRef.current.offsetWidth;
+            const newPageInfo = calculatePageBreakpoints(cumulativeWidths, scrollAreaWidth, contentTotalWidth, gap);
+            setPageInfo(newPageInfo);
+            providePageCount?.(newPageInfo.numberOfPages);
+        } else if (cards.length === 0 || !contentRef.current) {
+            setPageInfo({ breakpoints: [0], cardsPerPage: 0, numberOfPages: 1 });
+            providePageCount?.(1);
+        }
+    }, [width, cards, providePageCount, isDesktop]);
+
+    useEffect(() => {
+        if (currentPage > pageInfo.numberOfPages) {
+            setCurrentPage(pageInfo.numberOfPages);
+            setShowPreviousPageButton(pageInfo.numberOfPages > 1);
+        }
+    }, [currentPage, pageInfo.numberOfPages]);
+
+    useEffect(() => {
+        if (!shouldGoToPageBreakpoint || !contentRef.current || typeof contentRef.current.scrollTo !== 'function') {
+            return;
+        }
+        const scrollToPoint = pageInfo.breakpoints[currentPage - 1];
+        if (scrollToPoint === undefined) {
+            return;
+        }
+        let adjustedPoint = scrollToPoint;
+        if (cardOffset) {
+            const gapSize = isDesktop ? CAROUSEL_CARD_GAP_NUM : CAROUSEL_CARD_GAP_MOBILE_NUM;
+            adjustedPoint -= cardOffset + gapSize;
+        }
+        requestAnimationFrame(() => {
+            contentRef.current?.scrollTo({
+                behavior: 'smooth',
+                left: adjustedPoint,
+            });
+        });
+    }, [cardOffset, currentPage, isDesktop, pageInfo.breakpoints, shouldGoToPageBreakpoint]);
+
+    const onClickPageDotButton = useCallback((newPage: number) => {
+        setShouldGoToPageBreakpoint(true);
+        setCurrentPage(newPage);
+        setShowPreviousPageButton(newPage > 1);
+    }, []);
+
+    const pageDots = useMemo(() => {
+        if (pageInfo.numberOfPages === 1) {
+            return [];
+        }
+        const buttons = [];
+        for (let i = 1; i <= pageInfo.numberOfPages; i++) {
+            buttons.push(
+                <DotButton
+                    isActive={currentPage === i}
+                    key={i}
+                    onClick={() => {
+                        onClickPageDotButton(i);
+                    }}
+                    pageNumber={i}
+                />
+            );
+        }
+        return buttons;
+    }, [currentPage, onClickPageDotButton, pageInfo.numberOfPages]);
+
+    // Manually synced in goToNextPage, goToPreviousPage, onClickPageDotButton,
+    // selectedPage effect, and onScrollCards. This duplication is intentional:
+    // deriving it purely from currentPage would lose the scroll-position-based
+    // "show back button when any manual scroll has happened" behavior, and deriving
+    // it purely from the scroll handler would cause button flicker during the 50ms
+    // debounce window between setCurrentPage and the resulting scroll event.
+    const [showPreviousPageButton, setShowPreviousPageButton] = useState(false);
+
+    const goToPreviousPage = useCallback(() => {
+        if (currentPage > 1) {
+            setShouldGoToPageBreakpoint(true);
+            setCurrentPage(currentPage - 1);
+            goToPage?.({
+                buttonDirection: CarouselGoToPageDirection.Previous,
+            });
+        } else if (contentRef.current) {
+            contentRef.current.scrollLeft = 0;
+            goToPage?.({ oneBasedPageNumber: 1 });
+        }
+        setShowPreviousPageButton(currentPage - 1 > 1);
+    }, [currentPage, goToPage]);
+
+    const goToNextPage = useCallback(() => {
+        if (currentPage >= pageInfo.numberOfPages) {
+            return;
+        }
+        setShouldGoToPageBreakpoint(true);
+        setCurrentPage(currentPage + 1);
+        setShowPreviousPageButton(true);
+        goToPage?.({
+            buttonDirection: CarouselGoToPageDirection.Next,
+        });
+    }, [currentPage, goToPage, pageInfo.numberOfPages]);
+
+    useEffect(() => {
+        if (selectedPage) {
+            isProgrammaticScroll.current = true;
+            setShouldGoToPageBreakpoint(true);
+            setCurrentPage(selectedPage);
+            setShowPreviousPageButton(selectedPage > 1);
+        }
+    }, [selectedPage]);
+
+    const clearProgrammaticScrollFlag = useCallback(() => {
+        isProgrammaticScroll.current = false;
+    }, []);
+
+    /**
+     * Handles keyboard navigation for the carousel.
+     * Allows using Left and Right arrow keys to navigate between pages.
+     */
+    const onKeyNavigation: KeyboardEventHandler = useCallback(
+        (event) => {
+            if (event.key === 'ArrowRight') {
+                goToNextPage();
+            } else if (event.key === 'ArrowLeft') {
+                goToPreviousPage();
+            }
+        },
+        [goToNextPage, goToPreviousPage]
+    );
+
+    /**
+     * Handles scroll events within the carousel content area.
+     * Updates the current page and visibility of navigation buttons based on scroll position.
+     */
+    const onScrollCards: UIEventHandler<HTMLDivElement> = useCallback(() => {
+        if (!contentRef.current || isProgrammaticScroll.current) {
+            return;
+        }
+        const { clientWidth, scrollLeft, scrollWidth } = contentRef.current;
+        setShowPreviousPageButton(scrollLeft > 0);
+        setShouldGoToPageBreakpoint(false);
+
+        const isShowingAllOfLastPage = scrollWidth - scrollLeft <= clientWidth;
+
+        let resolvedPage: number;
+        if (isShowingAllOfLastPage) {
+            resolvedPage = pageInfo.numberOfPages;
+        } else {
+            // Find the last breakpoint the scroll position has reached or passed.
+            // breakpoints are sorted ascending; walk backwards for simplicity.
+            let pageIndex = 0;
+            for (let i = pageInfo.breakpoints.length - 1; i >= 0; i--) {
+                if (pageInfo.breakpoints[i] <= scrollLeft) {
+                    pageIndex = i;
+                    break;
+                }
+            }
+            resolvedPage = pageIndex + 1;
+        }
+
+        if (shouldGoToPageBreakpointsOnScrolling) {
+            setCurrentPage(resolvedPage);
+            goToPage?.({ oneBasedPageNumber: resolvedPage });
+        } else {
+            onScroll?.(resolvedPage);
+        }
+    }, [goToPage, onScroll, pageInfo, shouldGoToPageBreakpointsOnScrolling]);
+
+    const debouncedOnScrollCards = useMemo(() => debounce(onScrollCards, SCROLL_DEBOUNCE_TIME), [onScrollCards]);
+
+    useEffect(() => {
+        return () => debouncedOnScrollCards.cancel();
+    }, [debouncedOnScrollCards]);
+
+    const showNextPageButton =
+        currentPage < pageInfo.numberOfPages ||
+        // only use fullPage if the pageInfo is not yet populated
+        (fullPage && pageInfo.numberOfPages === 1 && cards.length > 1);
+
+    return (
+        <section
+            className={cn('relative w-full')}
+            ref={containerRef}
+        >
+            <div className={cn('flex items-end justify-between')}>
+                <TitleSection
+                    subHeaderDescription={subHeaderDescription}
+                    subHeaderLeft={subHeaderLeft}
+                    title={title}
+                    titleLink={titleLink}
+                    variant={variant}
+                />
+                <div className="flex h-full items-center gap-xs">
+                    {actionElement}
+                    <NavigationButtons
+                        goToNextPage={goToNextPage}
+                        goToPreviousPage={goToPreviousPage}
+                        showNextPageButton={showNextPageButton}
+                        showPreviousPageButton={showPreviousPageButton}
+                        useOverlayControls={useOverlayControls}
+                        variant={variant}
+                    />
+                </div>
+            </div>
+            {/* IF YOU CHANGE GAP BETWEEN CARDS HERE, YOU MUST ALSO ADJUST THE BREAKPOINT CALCULATION FORMULA TO ACCOUNT FOR THAT GAP */}
+            <div className={cn('mt-sm w-full overflow-hidden xsMax:-mx-sm xsMax:w-[calc(100%+32px)]')}>
+                {/* onKeyUp is used to arrow key right and left to pages */}
+                {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */}
+                <div
+                    aria-label={`Slide ${currentPage} of ${pageInfo.numberOfPages}`}
+                    aria-live="polite"
+                    className={cn(
+                        'flex gap-md overflow-y-hidden overflow-x-scroll xsMax:gap-sm',
+                        'xsMax:snap-x xsMax:snap-mandatory xsMax:scroll-pl-sm xsMax:scroll-pr-sm',
+                        'backface-hidden transform-gpu will-change-scroll contain-layout'
+                    )}
+                    onKeyUp={onKeyNavigation}
+                    onScroll={debouncedOnScrollCards}
+                    onTouchMoveCapture={clearProgrammaticScrollFlag}
+                    onWheelCapture={clearProgrammaticScrollFlag}
+                    ref={contentRef}
+                    role="list"
+                    style={{
+                        scrollbarWidth: 'none',
+                    }}
+                >
+                    {carouselCards}
+                </div>
+            </div>
+            {showPagination && (
+                <div
+                    aria-label={`${title} carousel page selector`}
+                    className={cn('mt-sm flex justify-center gap-xs')}
+                    role="tablist"
+                >
+                    {pageDots}
+                </div>
+            )}
+        </section>
+    );
+};

package/src/Carousel/Carousel.types.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+
+export type CarouselCard = {
+    /**
+     * The rendered content of the card
+     */
+    card: ReactNode;
+    /**
+     * The unique identifier for the card
+     */
+    key: string;
+};
+
+export type CarouselPageInfo = {
+    breakpoints: number[];
+    cardsPerPage: number;
+    numberOfPages: number;
+};
+
+// this is the px size of the MD gap
+export const CAROUSEL_CARD_GAP_NUM = 24;
+export const CAROUSEL_CARD_GAP_MOBILE_NUM = 16;
+
+export enum CarouselGoToPageDirection {
+    Previous = -1,
+    Next = 1,
+}
+
+/**
+ * Page navigation information based on the action the user took.
+ *
+ * @property {CarouselGoToPageDirection} buttonDirection - Populated if the user clicked the Next or Previous buttons
+ * @property {number} oneBasedPageNumber - The user navigated between cards by scrolling/dragging manually
+ */
+export type CarouselGoToPageInfo =
+    | {
+          buttonDirection: CarouselGoToPageDirection;
+          oneBasedPageNumber?: never;
+      }
+    | {
+          buttonDirection?: never;
+          oneBasedPageNumber: number;
+      };

package/src/Carousel/Carousel.utils.ts

@@ -0,0 +1,63 @@
+import { CarouselPageInfo } from './Carousel.types';
+
+/**
+ * Pure function that calculates page breakpoints from cumulative card positions.
+ *
+ * @param cumulativeWidths - Array of cumulative widths (including inter-card gaps) for each card.
+ *   Each entry is the total width from the start through that card, including a trailing gap
+ *   for every card except the last.
+ * @param scrollAreaWidth - The visible width of the scroll container.
+ * @param contentTotalWidth - The total width of all cards and gaps combined.
+ * @param gap - The gap size (in px) between cards.
+ */
+export const calculatePageBreakpoints = (
+    cumulativeWidths: number[],
+    scrollAreaWidth: number,
+    contentTotalWidth: number,
+    gap: number
+): CarouselPageInfo => {
+    if (cumulativeWidths.length === 0 || scrollAreaWidth <= 0) {
+        return { breakpoints: [0], cardsPerPage: 0, numberOfPages: 1 };
+    }
+
+    const cardsPerPageCounts: number[] = [];
+    // Starts at 1 because the first card (index 0) is already on the current page;
+    // the loop below begins at index 1.
+    let currentCardsPerPage = 1;
+    let numberOfPages = 1;
+    const pageBreakpoints = [0];
+    let pageStartCumulative = 0;
+
+    for (let index = 1; index < cumulativeWidths.length; index++) {
+        // Subtract the trailing gap so we measure only the visual width of cards + inner gaps on this page.
+        // The last card in the input never has a trailing gap, but intermediate cards do.
+        const isLastCard = index === cumulativeWidths.length - 1;
+        const trailingGap = isLastCard ? 0 : gap;
+        const pageWidth = cumulativeWidths[index] - pageStartCumulative - trailingGap;
+
+        if (pageWidth > scrollAreaWidth) {
+            numberOfPages++;
+            pageBreakpoints.push(cumulativeWidths[index - 1]);
+            cardsPerPageCounts.push(currentCardsPerPage);
+            pageStartCumulative = cumulativeWidths[index - 1];
+            currentCardsPerPage = 1;
+        } else {
+            currentCardsPerPage++;
+        }
+    }
+
+    // Include the last page's card count in the max calculation
+    cardsPerPageCounts.push(currentCardsPerPage);
+
+    const lastBreakpoint = pageBreakpoints[pageBreakpoints.length - 1] || 0;
+    if (contentTotalWidth - lastBreakpoint > scrollAreaWidth) {
+        numberOfPages++;
+        pageBreakpoints.push(contentTotalWidth - scrollAreaWidth);
+    }
+
+    return {
+        breakpoints: pageBreakpoints,
+        cardsPerPage: Math.max(...cardsPerPageCounts),
+        numberOfPages,
+    };
+};

package/src/Carousel/components/DotButton/DotButton.tsx

@@ -0,0 +1,42 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { Tooltip } from '../../../Tooltip/Tooltip';
+
+type Props = {
+    isActive: boolean;
+    onClick: () => void;
+    pageNumber: number;
+};
+
+export const DotButton = ({ isActive, onClick, pageNumber }: Props) => {
+    const baseStyles = cn('h-xs w-xs rounded-full border-none hover:cursor-pointer');
+    const styles = isActive
+        ? cn(baseStyles, 'bg-text-primary hover:bg-text-secondary')
+        : cn(baseStyles, 'bg-text-inactive hover:bg-text-secondary');
+    // Generate deterministic ID from pageNumber for SSR compatibility
+    const tooltipId = `carousel-dot-page-${pageNumber}`;
+
+    return (
+        <>
+            {/*
+                this uses a regular HTML button because our Button component doesn't get small enough to be completely circular.
+                this is solving an edgecase and this pattern should be avoided for any other kind of button
+            */}
+            <button
+                aria-controls="carousel-track"
+                aria-label={`Page ${pageNumber}`}
+                aria-selected={isActive}
+                className={styles}
+                data-testid="dot-button"
+                data-tooltip-id={tooltipId}
+                onClick={onClick}
+                role="tab"
+            />
+            <Tooltip
+                content={`Page ${pageNumber}`}
+                delayShow={50}
+                id={tooltipId}
+            />
+        </>
+    );
+};