@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Callout/Callout.tsx

@@ -0,0 +1,136 @@
+'use client';
+
+import { cn } from '@evolve.ui/theme-system';
+
+import type { CalloutProps, CalloutStatus } from './Callout.types';
+
+import { Button } from '../Button/Button';
+import { IconButton } from '../IconButton/IconButton';
+import { Close } from '../Icons';
+import { BodySecondary, H5 } from '../Typography/Text/Text';
+import { CalloutIcon } from './components/CalloutIcon/CalloutIcon';
+
+const statusClasses = {
+    critical: 'border-border-critical bg-background-critical-light',
+    info: 'border-border-info bg-background-info-light',
+    success: 'border-border-success bg-background-success-light',
+    warning: 'border-border-warning bg-background-warning-light',
+} satisfies Record<CalloutStatus, string>;
+
+export const Callout = ({
+    badge = undefined,
+    className,
+    message,
+    onClose,
+    primaryButton,
+    secondaryButton,
+    status = 'info',
+    title,
+    useNonSemanticHTML = false,
+}: CalloutProps) => {
+    const hasActions = Boolean(primaryButton) || Boolean(secondaryButton);
+    const hasCloseButton = Boolean(onClose) && status !== 'critical';
+
+    return (
+        <div
+            className={cn(
+                'grid gap-x-sm rounded-input border p-md',
+                'grid-cols-[min-content_1fr_min-content]',
+                hasCloseButton && 'grid-cols-[min-content_1fr_min-content_min-content]',
+                'smMax:grid-cols-[min-content_1fr_min-content]',
+                statusClasses[status],
+                className
+            )}
+            data-hui-id="Callout"
+            role={status === 'critical' ? 'alert' : undefined}
+        >
+            {badge ?? <CalloutIcon status={status} />}
+
+            <div className="flex flex-col justify-center">
+                {title &&
+                    (useNonSemanticHTML ? (
+                        <span
+                            className="hui-text-h5 col-start-2 mb-2xs text-text-primary"
+                            data-testid="callout-title"
+                        >
+                            {title}
+                        </span>
+                    ) : (
+                        <H5
+                            className="col-start-2 mb-2xs"
+                            data-testid="callout-title"
+                        >
+                            {title}
+                        </H5>
+                    ))}
+
+                <BodySecondary className="col-start-2 min-w-0 break-words">{message}</BodySecondary>
+
+                {hasActions && (
+                    <div className="col-start-2 mt-sm hidden items-center smMax:flex">
+                        {primaryButton && (
+                            <Button
+                                className="mr-sm"
+                                onClick={primaryButton.onClick}
+                                size="sm"
+                                style={primaryButton.style ?? 'primary'}
+                                variant={primaryButton.variant ?? 'outlined'}
+                            >
+                                {primaryButton.text}
+                            </Button>
+                        )}
+                        {secondaryButton && (
+                            <Button
+                                className="mr-sm"
+                                onClick={secondaryButton.onClick}
+                                size="sm"
+                                style={secondaryButton.style ?? 'primary'}
+                                variant={secondaryButton.variant ?? 'transparent'}
+                            >
+                                {secondaryButton.text}
+                            </Button>
+                        )}
+                    </div>
+                )}
+            </div>
+
+            {hasActions && (
+                <div className="flex h-full items-start gap-sm smMax:hidden">
+                    {primaryButton && (
+                        <Button
+                            data-testid="primary-button"
+                            onClick={primaryButton.onClick}
+                            size="sm"
+                            style={primaryButton.style ?? 'primary'}
+                            variant={primaryButton.variant ?? 'outlined'}
+                        >
+                            {primaryButton.text}
+                        </Button>
+                    )}
+                    {secondaryButton && (
+                        <Button
+                            data-testid="secondary-button"
+                            onClick={secondaryButton.onClick}
+                            size="sm"
+                            style={secondaryButton.style ?? 'primary'}
+                            variant={secondaryButton.variant ?? 'transparent'}
+                        >
+                            {secondaryButton.text}
+                        </Button>
+                    )}
+                </div>
+            )}
+
+            {hasCloseButton && (
+                <IconButton
+                    aria-label="Close"
+                    icon={Close}
+                    onClick={onClose}
+                    size="sm"
+                />
+            )}
+        </div>
+    );
+};
+
+Callout.displayName = 'Callout';

package/src/Callout/Callout.types.ts

@@ -0,0 +1,29 @@
+import type { ComponentProps, ReactElement, ReactNode } from 'react';
+
+import type { Badge } from '../Badge/Badge';
+import type { ButtonStyle, ButtonVariant } from '../Button/Button.types';
+
+export type CalloutStatus = 'info' | 'warning' | 'success' | 'critical';
+
+export type CalloutButtonConfig = {
+    onClick: () => void;
+    style?: ButtonStyle;
+    text: string;
+    variant?: ButtonVariant;
+};
+
+export type CalloutProps = {
+    /** Optional Badge component displayed in place of the default status icon. */
+    badge?: ReactElement<ComponentProps<typeof Badge>>;
+    className?: string;
+    message?: string | ReactNode;
+    onClose?: () => void;
+    primaryButton?: CalloutButtonConfig;
+    secondaryButton?: CalloutButtonConfig;
+    status: CalloutStatus;
+    title?: string;
+    /**
+     * Renders the title as a span with H5 styling instead of a semantic heading.
+     */
+    useNonSemanticHTML?: boolean;
+};

package/src/Callout/components/CalloutIcon/CalloutIcon.tsx

@@ -0,0 +1,56 @@
+import type { CalloutStatus } from '../../Callout.types';
+
+import { CheckCircle, Info, Warning } from '../../../Icons';
+
+type CalloutIconProps = {
+    status: CalloutStatus;
+};
+
+export const CalloutIcon = ({ status }: CalloutIconProps) => {
+    if (status === 'critical') {
+        return (
+            <div className="col-start-1 row-start-1">
+                <Warning
+                    color="critical"
+                    size="md"
+                    style="fill"
+                />
+            </div>
+        );
+    }
+
+    if (status === 'success') {
+        return (
+            <div className="col-start-1 row-start-1">
+                <CheckCircle
+                    color="success"
+                    style="fill"
+                />
+            </div>
+        );
+    }
+
+    if (status === 'warning') {
+        return (
+            <div className="col-start-1 row-start-1">
+                <Warning
+                    color="warning"
+                    size="md"
+                    style="fill"
+                />
+            </div>
+        );
+    }
+
+    return (
+        <div className="col-start-1 row-start-1">
+            <Info
+                color="info"
+                size="md"
+                style="fill"
+            />
+        </div>
+    );
+};
+
+CalloutIcon.displayName = 'CalloutIcon';

package/src/Card/CardGrid.tsx

@@ -0,0 +1,263 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useCallback, useMemo } from 'react';
+
+import { nodeEnv } from '../utils/nodeEnv';
+import { useCardVisibilityTracking } from './hooks/useCardVisibilityTracking';
+import { SharedProps } from './sharedProps';
+
+type SpacingToken = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+type Props<CardData, KeyType extends string | number> = {
+    /**
+     * The data to pass to the card components.
+     */
+    cardData: Record<KeyType, CardData>;
+    /**
+     * Which cards to render. These should all be keys in `cardData`.
+     *
+     * If this is empty, then `skeletonCardCount` skeleton cards will be rendered (if set).
+     */
+    cards: KeyType[];
+    className?: string;
+    /**
+     * The number of columns to display at each breakpoint.
+     *
+     * @default { xs: 2, sm: 3, md: 4, lg: 4, xl: 4 }
+     */
+    colsByBreakpoint: { xs: number } & { [key in 'sm' | 'md' | 'lg' | 'xl']?: number };
+    /**
+     * The gap between cards at each breakpoint.
+     * gapsByBreakpoint: { xs: 'xs' } means that the gap at xsMax breakpoint is 8px.
+     *
+     * @default { xs: 'sm', sm: 'sm', md: 'md', lg: 'md', xl: 'md' }
+     */
+    gapsByBreakpoint: {
+        // lgMax: { max: '1644px' },
+        lg?: SpacingToken;
+        // mdMax: { max: '1248px' },
+        md?: SpacingToken;
+        // smMax: { max: '1023px' },
+        sm?: SpacingToken;
+        // lgMin: { min: '1249px' },
+        xl?: SpacingToken;
+        // xsMax: { max: '768px' },
+        xs?: SpacingToken;
+    };
+    /**
+     * Optional callback function to call when a card is clicked.
+     * The card data is passed to the function.
+     * Note: This should be handled by specific clickable elements within the card (links, buttons)
+     * rather than the card wrapper itself.
+     */
+    onCardClick?: (cardData: CardData) => void;
+    /**
+     * The function to call when a card becomes visible in the viewport.
+     * This callback fires only once per card when it first becomes visible.
+     * The card data is passed to the function.
+     */
+    onCardVisible?: (cardData: CardData) => void;
+    /**
+     * The number of skeleton cards to render.
+     *
+     * This is ignored if `cards` is nonempty.
+     */
+    skeletonCardCount?: number;
+} & SharedProps<CardData>;
+
+export const CardGrid = <CardData, KeyType extends string | number>({
+    card: Card,
+    cardData,
+    cards,
+    className,
+    // Default values that work well for 4 column grid
+    colsByBreakpoint = {
+        lg: 4,
+        md: 4,
+        sm: 3,
+        xl: 4,
+        xs: 2,
+    },
+    forceSkeleton = false,
+    // Default values that work well for 4 column grid
+    gapsByBreakpoint = {
+        lg: 'md',
+        md: 'md',
+        sm: 'sm',
+        xl: 'md',
+        xs: 'sm',
+    },
+    onCardClick,
+    onCardVisible,
+    skeletonCardCount = 0,
+}: Props<CardData, KeyType>) => {
+    const doesGridHaveLoadedData = cards.length > 0 && Object.keys(cardData).length > 0 && !forceSkeleton;
+
+    const gridClasses = useMemo(
+        () =>
+            cn(
+                'grid',
+                `grid-cols-${colsByBreakpoint.xs}`,
+                `gap-${gapsByBreakpoint.xs}`,
+                {
+                    'lgMax:gap-lg': gapsByBreakpoint.lg === 'lg',
+                    'lgMax:gap-md': gapsByBreakpoint.lg === 'md',
+                    'lgMax:gap-sm': gapsByBreakpoint.lg === 'sm',
+                    'lgMax:gap-xl': gapsByBreakpoint.lg === 'xl',
+                    'lgMax:gap-xs': gapsByBreakpoint.lg === 'xs',
+
+                    'lgMax:grid-cols-1': colsByBreakpoint.lg === 1,
+                    'lgMax:grid-cols-2': colsByBreakpoint.lg === 2,
+                    'lgMax:grid-cols-3': colsByBreakpoint.lg === 3,
+                    'lgMax:grid-cols-4': colsByBreakpoint.lg === 4,
+                    'lgMax:grid-cols-5': colsByBreakpoint.lg === 5,
+                    'lgMax:grid-cols-6': colsByBreakpoint.lg === 6,
+
+                    'lgMin:gap-lg': gapsByBreakpoint.lg === 'lg',
+                    'lgMin:gap-md': gapsByBreakpoint.lg === 'md',
+                    'lgMin:gap-sm': gapsByBreakpoint.lg === 'sm',
+                    'lgMin:gap-xl': gapsByBreakpoint.lg === 'xl',
+                    'lgMin:gap-xs': gapsByBreakpoint.lg === 'xs',
+
+                    // Min-width breakpoints for largest size (lgMin)
+                    'lgMin:grid-cols-1': colsByBreakpoint.lg === 1,
+                    'lgMin:grid-cols-2': colsByBreakpoint.lg === 2,
+                    'lgMin:grid-cols-3': colsByBreakpoint.lg === 3,
+                    'lgMin:grid-cols-4': colsByBreakpoint.lg === 4,
+                    'lgMin:grid-cols-5': colsByBreakpoint.lg === 5,
+                    'lgMin:grid-cols-6': colsByBreakpoint.lg === 6,
+                    'mdMax:gap-lg': gapsByBreakpoint.md === 'lg',
+                    'mdMax:gap-md': gapsByBreakpoint.md === 'md',
+                    'mdMax:gap-sm': gapsByBreakpoint.md === 'sm',
+                    'mdMax:gap-xl': gapsByBreakpoint.md === 'xl',
+                    'mdMax:gap-xs': gapsByBreakpoint.md === 'xs',
+
+                    'mdMax:grid-cols-1': colsByBreakpoint.md === 1,
+                    'mdMax:grid-cols-2': colsByBreakpoint.md === 2,
+                    'mdMax:grid-cols-3': colsByBreakpoint.md === 3,
+                    'mdMax:grid-cols-4': colsByBreakpoint.md === 4,
+                    'mdMax:grid-cols-5': colsByBreakpoint.md === 5,
+                    'mdMax:grid-cols-6': colsByBreakpoint.md === 6,
+
+                    'smMax:gap-lg': gapsByBreakpoint.sm === 'lg',
+                    'smMax:gap-md': gapsByBreakpoint.sm === 'md',
+                    'smMax:gap-sm': gapsByBreakpoint.sm === 'sm',
+                    'smMax:gap-xl': gapsByBreakpoint.sm === 'xl',
+                    'smMax:gap-xs': gapsByBreakpoint.sm === 'xs',
+
+                    'smMax:grid-cols-1': colsByBreakpoint.sm === 1,
+                    'smMax:grid-cols-2': colsByBreakpoint.sm === 2,
+                    'smMax:grid-cols-3': colsByBreakpoint.sm === 3,
+                    'smMax:grid-cols-4': colsByBreakpoint.sm === 4,
+                    'smMax:grid-cols-5': colsByBreakpoint.sm === 5,
+                    'smMax:grid-cols-6': colsByBreakpoint.sm === 6,
+                    'xsMax:gap-lg': gapsByBreakpoint.xs === 'lg',
+                    'xsMax:gap-md': gapsByBreakpoint.xs === 'md',
+                    'xsMax:gap-sm': gapsByBreakpoint.xs === 'sm',
+                    'xsMax:gap-xl': gapsByBreakpoint.xs === 'xl',
+
+                    // Max-width breakpoints for gaps
+                    'xsMax:gap-xs': gapsByBreakpoint.xs === 'xs',
+                    // Max-width breakpoints for columns
+
+                    'xsMax:grid-cols-1': colsByBreakpoint.xs === 1,
+                    'xsMax:grid-cols-2': colsByBreakpoint.xs === 2,
+                    'xsMax:grid-cols-3': colsByBreakpoint.xs === 3,
+                    'xsMax:grid-cols-4': colsByBreakpoint.xs === 4,
+                    'xsMax:grid-cols-5': colsByBreakpoint.xs === 5,
+                    'xsMax:grid-cols-6': colsByBreakpoint.xs === 6,
+                },
+                className
+            ),
+        [
+            className,
+            colsByBreakpoint.lg,
+            colsByBreakpoint.md,
+            colsByBreakpoint.sm,
+            colsByBreakpoint.xs,
+            gapsByBreakpoint.lg,
+            gapsByBreakpoint.md,
+            gapsByBreakpoint.sm,
+            gapsByBreakpoint.xs,
+        ]
+    );
+
+    // Memoize the card click handler
+    const handleCardClick = useCallback(
+        (cardData: CardData) => {
+            onCardClick?.(cardData);
+        },
+        [onCardClick]
+    );
+
+    return (
+        <div className={gridClasses}>
+            {doesGridHaveLoadedData ? (
+                <LoadedCardGrid
+                    card={Card}
+                    cardData={cardData}
+                    cards={cards}
+                    onCardClick={handleCardClick}
+                    onCardVisible={onCardVisible}
+                />
+            ) : (
+                new Array(skeletonCardCount).fill(0).map((_, i) => <Card.Skeleton key={i} />)
+            )}
+        </div>
+    );
+};
+
+/**
+ * This grid is the one that does the checks / we are sure that the card data is loaded.
+ */
+const LoadedCardGrid = <CardData, KeyType extends string | number>({
+    card: Card,
+    cardData,
+    cards,
+    onCardClick,
+    onCardVisible,
+}: Pick<Props<CardData, KeyType>, 'card' | 'cardData' | 'cards' | 'onCardClick' | 'onCardVisible' | 'className'>) => {
+    // Development only checks.
+    if (nodeEnv !== 'production') {
+        for (const card of cards) {
+            if (!cardData[card]) {
+                // eslint-disable-next-line no-console
+                console.error(`Card data does not have card with id '${card}'`);
+            }
+        }
+    }
+
+    // Wrap the onCardVisible callback to map card keys back to card data
+    const handleCardVisible = useCallback(
+        (cardKey: KeyType) => {
+            if (onCardVisible && cardData[cardKey]) {
+                onCardVisible(cardData[cardKey]);
+            }
+        },
+        [onCardVisible, cardData]
+    );
+
+    // Set up visibility tracking - only create if callback is provided
+    const getVisibilityRef = useCardVisibilityTracking<KeyType>(handleCardVisible, { threshold: 0.5 });
+
+    return useMemo(
+        () =>
+            cards
+                .filter((card) => {
+                    if (!cardData[card]) {
+                        // eslint-disable-next-line no-console
+                        console.error(`Card data does not have card with id '${card}'`);
+                        return false;
+                    }
+                    return true;
+                })
+                .map((card) => (
+                    <Card.Normal
+                        cardData={cardData[card]}
+                        key={card}
+                        onCardClick={onCardClick}
+                        visibilityRef={onCardVisible ? getVisibilityRef(card) : undefined}
+                    />
+                )),
+        [cards, cardData, Card, onCardClick, onCardVisible, getVisibilityRef]
+    );
+};

package/src/Card/SingleCard.tsx

@@ -0,0 +1,22 @@
+import { SharedProps } from './sharedProps';
+
+type Props<CardData> = {
+    className?: string;
+    /**
+     * The data to pass to the card component.
+     */
+    data: CardData;
+} & SharedProps<CardData>;
+
+export const SingleCard = <CardData,>({ card: Card, className, data, forceSkeleton }: Props<CardData>) => {
+    if (forceSkeleton) {
+        return <Card.Skeleton className={className} />;
+    }
+
+    return (
+        <Card.Normal
+            cardData={data}
+            className={className}
+        />
+    );
+};

package/src/Card/cardFactory.tsx

@@ -0,0 +1,176 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ReactNode, useMemo } from 'react';
+
+import { Skeleton } from '../Skeleton/Skeleton';
+import { CardComponent, CardSpec, isSpacer } from './types';
+
+export { type CardComponent, type CardSpec };
+
+export type CreatedCard<CardData> = ReturnType<typeof cardFactory<CardData>>;
+
+/**
+ * This function takes a `CardSpec` and returns a React component.
+ *
+ * This function should be called _once_ for each card spec.
+ * You can export the result of this function and use it in your app later.
+ */
+export const cardFactory = <CardData,>(cardSpec: CardSpec<CardData>) => {
+    const { components: oldComponents, name } = cardSpec;
+
+    if (!oldComponents.length) {
+        throw new Error('Card must have at least one component');
+    }
+
+    let componentCount: number = 0;
+    const components: CardComponent<CardData>[] = [];
+    const spacing: number[] = new Array(oldComponents.length).fill(0);
+
+    let currentSkeletonOffset = 0;
+    const skeletonComponents: ReactNode[] = [];
+
+    for (const componentOrSpace of oldComponents) {
+        if (isSpacer(componentOrSpace)) {
+            if (componentCount === 0) {
+                throw new Error('Card cannot start with a spacer');
+            }
+
+            currentSkeletonOffset += componentOrSpace.spacerPx;
+            spacing[componentCount] += componentOrSpace.spacerPx;
+
+            continue;
+        }
+
+        const component = componentOrSpace;
+        components.push(component);
+
+        if (component.skeletonConfig) {
+            const skeletonConfig = component.skeletonConfig;
+            if (skeletonConfig.type === 'inline' && skeletonConfig.width && skeletonConfig.height) {
+                skeletonComponents.push(
+                    <rect
+                        height={skeletonConfig.height}
+                        key={componentCount}
+                        rx={skeletonConfig.rx ?? 4}
+                        ry={skeletonConfig.ry ?? 4}
+                        width={skeletonConfig.width}
+                        x="0"
+                        y={currentSkeletonOffset}
+                    />
+                );
+
+                currentSkeletonOffset += skeletonConfig.height;
+            } else if (skeletonConfig.type === 'absolute') {
+                skeletonComponents.push(skeletonConfig.node);
+            }
+        }
+
+        componentCount++;
+    }
+
+    const Normal = ({
+        cardData,
+        className,
+        onCardClick,
+        visibilityRef,
+    }: {
+        cardData: CardData;
+        className?: string;
+        /** Optional click handler for the card */
+        onCardClick?: (cardData: CardData) => void;
+        /** Ref callback for visibility tracking */
+        visibilityRef?: (element: Element | null) => void;
+    }) => {
+        return (
+            <CardContainer
+                className={cn('group', cardSpec.className, className)}
+                // @ts-expect-error id is not part of the card data, but can be added by the caller
+                id={cardData?.id ?? undefined}
+                onClick={onCardClick ? () => onCardClick(cardData) : undefined}
+                spacing={spacing}
+                visibilityRef={visibilityRef}
+            >
+                {/* The components will never change, so using index here is ok. */}
+                {components.map((component, index) => (
+                    <component.Component
+                        {...cardData}
+                        key={index}
+                    />
+                ))}
+            </CardContainer>
+        );
+    };
+    Normal.displayName = name;
+    const CardSkeleton = ({ className }: { className?: string }) => {
+        return (
+            <CardContainer
+                className={cn(cardSpec.className, className)}
+                isSkeleton
+                spacing={spacing}
+            >
+                <Skeleton viewBox={`0 0 282 ${cardSpec.overrideSkeletonHeightPx ?? currentSkeletonOffset}`}>
+                    {skeletonComponents}
+                </Skeleton>
+            </CardContainer>
+        );
+    };
+    CardSkeleton.displayName = name + 'Skeleton';
+
+    const Card = {
+        Normal,
+        Skeleton: CardSkeleton,
+    };
+
+    return Card;
+};
+
+type CardContainerProps = {
+    children: ReactNode;
+    className?: string;
+    isSkeleton?: boolean;
+    onClick?: () => void;
+    spacing: number[];
+    visibilityRef?: (element: Element | null) => void;
+};
+
+const CardContainer = ({
+    children,
+    className,
+    isSkeleton,
+    onClick,
+    spacing,
+    visibilityRef,
+    ...props
+}: CardContainerProps) => {
+    const { styles } = useMemo(() => {
+        const styles = {} as { [key: string]: string };
+
+        spacing.forEach((space, i) => {
+            if (space !== 0) {
+                const key = `--card-spacing-${i}`;
+                styles[key] = `${space}px`;
+            }
+        });
+
+        return {
+            styles: styles as React.CSSProperties,
+        };
+    }, [spacing]);
+
+    const Container = isSkeleton ? 'div' : 'article';
+
+    return (
+        <Container
+            className={cn(
+                // Base spacing classes
+                'hui-item-card relative flex w-full flex-col',
+                className
+            )}
+            onClick={onClick}
+            ref={visibilityRef}
+            style={styles}
+            {...props}
+        >
+            {children}
+        </Container>
+    );
+};