@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/ProgressCircle/ProgressCircle.tsx

@@ -0,0 +1,246 @@
+import { colorIconDisabled, colorIconSecondary, colorIconSuccess } from '@evolve.ui/theme-system';
+import { ReactNode } from 'react';
+
+import { CheckCircle } from '../Icons/generatedIcons/CheckCircle';
+import { getColor, IconProps } from '../Icons/IconBase';
+import { useProgressStatusTransitions } from './hooks/useProgressStatusTransitions';
+import {
+    CIRCLE_RADIUS,
+    circleBaseProps,
+    DASHED_PATTERN,
+    ICON_CONTAINER_SIZE,
+    progressCircleOuterSizes,
+    SPINNER_ARC_SIZE,
+    VIEWBOX_SIZE,
+    WAVE_ARC_SIZE,
+    WAVE_OFFSET,
+} from './utils/progressCircle.constants';
+
+type ProgressCircleProps = {
+    'aria-label'?: string;
+    centerIcon?: ReactNode;
+    className?: string;
+    color?: Exclude<IconProps['color'], 'disabled' | 'inherit'>;
+    'data-testid'?: string;
+    indeterminateAnimation?: 'spinner' | 'wave';
+    /**
+     * Progress value from 0-100. Only used when status is 'progressing'.
+     * If not provided while status is 'progressing', an indeterminate animation will be shown instead.
+     */
+    progress?: number;
+    size?: keyof typeof progressCircleOuterSizes;
+    /**
+     * Current status of the operation:
+     * - 'pending': Shows dashed circle with gray arrow (not yet started)
+     * - 'progressing': Shows progress animation. If `progress` is not provided, automatically shows indeterminate animation
+     * - 'complete': Shows full circle with success checkmark animation
+     * - 'indeterminate': Always shows indeterminate animation, even if progress value is provided (use for explicit indeterminate state)
+     */
+    status?: 'pending' | 'progressing' | 'complete' | 'indeterminate';
+};
+
+export const ProgressCircle = ({
+    'aria-label': ariaLabel = 'Progress Circle',
+    centerIcon,
+    className,
+    color = 'secondary',
+    'data-testid': dataTestId,
+    indeterminateAnimation = 'spinner',
+    progress,
+    size = 'md',
+    status = 'pending',
+}: ProgressCircleProps) => {
+    const outerSize = progressCircleOuterSizes[size];
+
+    const strokeColor = getColor(color) ?? `rgb(var(${colorIconSecondary}))`;
+    const grayColor = `rgb(var(${colorIconDisabled}))`;
+    const successColor = `rgb(var(${colorIconSuccess}))`;
+
+    // Status flags for cleaner conditionals
+    const isPending = status === 'pending';
+    const isProgressing = status === 'progressing';
+    const isComplete = status === 'complete';
+    const isIndeterminate = status === 'indeterminate';
+
+    // When status is complete, always use success color for the progress circle
+    const progressCircleColor = isComplete ? successColor : strokeColor;
+
+    // Arrow color changes based on status: gray when pending, colored otherwise
+    const arrowColor = isPending ? grayColor : strokeColor;
+
+    // Calculate circle circumference for progress animation
+    const circumference = 2 * Math.PI * CIRCLE_RADIUS;
+
+    // Calculate foreignObject dimensions - centered in viewBox
+    const iconViewBoxOffset = (VIEWBOX_SIZE - ICON_CONTAINER_SIZE) / 2;
+
+    // Transition state from custom hook
+    const { animateToSolidCircle, isShowingCompletion } = useProgressStatusTransitions(status);
+
+    // Show fill and progress circles only when progressing or complete
+    const showProgressCircles = isProgressing || isComplete;
+
+    // Auto-set progress to 100% when status is complete
+    // Default to 0 if progress is undefined (though this should only be used when showProgressArc is true)
+    const resolvedProgressValue = isComplete ? 100 : (progress ?? 0);
+
+    // Gray fill circle: animates from circumference to 0 when animateToSolidCircle is true
+    const grayFillOffset = animateToSolidCircle ? 0 : circumference;
+
+    // Colored progress circle: tied to effective progress value (100% when complete)
+    const progressOffset = circumference - (resolvedProgressValue / 100) * circumference;
+
+    // Conditional rendering logic for indeterminate vs progress modes
+    // Show indeterminate if explicitly set OR if progressing without progress value
+    const hasProgressValue = typeof progress === 'number';
+    const isIndeterminateMode = isIndeterminate || (isProgressing && !hasProgressValue);
+    const showIndeterminateSpinner = isIndeterminateMode && animateToSolidCircle;
+    const showProgressArc = !isIndeterminateMode && showProgressCircles;
+    const showGrayFill = isIndeterminateMode || showProgressCircles;
+
+    // CSS custom properties for the wave animation keyframes (defined in plugin.ts).
+    // These must be inline styles because the values are calculated from the
+    // circle's circumference, which is derived from CIRCLE_RADIUS based off chosen size (sm, md, lg) at runtime.
+    const waveAnimationStyles = {
+        '--progress-wave-end': `1 ${circumference}`,
+        '--progress-wave-full': `${-circumference}`,
+        '--progress-wave-mid': `${circumference * WAVE_ARC_SIZE} ${circumference}`,
+        '--progress-wave-offset': `${-circumference * WAVE_OFFSET}`,
+        '--progress-wave-start': `1 ${circumference}`,
+    } as React.CSSProperties;
+
+    // Determine ARIA attributes based on whether we're showing determinate or indeterminate
+    // Show progressbar role only when actively progressing with progress value
+    // Complete status should be 'status' role, not 'progressbar'
+    const ariaRole = showProgressArc && !isComplete ? 'progressbar' : 'status';
+    const ariaBusy = isIndeterminateMode || isProgressing;
+    const ariaValueNow = showProgressArc ? resolvedProgressValue : undefined;
+
+    return (
+        <span
+            className={className}
+            data-testid={dataTestId}
+            style={waveAnimationStyles}
+        >
+            <svg
+                aria-busy={ariaBusy}
+                aria-label={ariaLabel}
+                aria-live="polite"
+                aria-valuemax={showProgressArc ? 100 : undefined}
+                aria-valuemin={showProgressArc ? 0 : undefined}
+                aria-valuenow={ariaValueNow}
+                className={
+                    isShowingCompletion
+                        ? `min-h-[${outerSize}px] min-w-[${outerSize}px] animate-progress-completion`
+                        : `min-h-[${outerSize}px] min-w-[${outerSize}px]`
+                }
+                fill="none"
+                height={outerSize}
+                role={ariaRole}
+                viewBox={`0 0 ${VIEWBOX_SIZE} ${VIEWBOX_SIZE}`}
+                width={outerSize}
+                xmlns="http://www.w3.org/2000/svg"
+            >
+                {/* Dashed background circle */}
+                <circle
+                    {...circleBaseProps}
+                    stroke={grayColor}
+                    strokeDasharray={DASHED_PATTERN}
+                />
+
+                {/* Gray fill circle - animates 0→100% in 300ms when status is progressing or indeterminate */}
+                {showGrayFill && (
+                    <circle
+                        {...circleBaseProps}
+                        className="origin-center -rotate-90 transition-[stroke-dashoffset] duration-300"
+                        stroke={grayColor}
+                        strokeDasharray={circumference}
+                        strokeDashoffset={grayFillOffset}
+                        strokeLinecap="round"
+                    />
+                )}
+
+                {/* Indeterminate spinner - 1/4 circle arc that rotates */}
+                {showIndeterminateSpinner && indeterminateAnimation === 'spinner' && (
+                    <circle
+                        {...circleBaseProps}
+                        className="origin-center animate-spin"
+                        stroke={strokeColor}
+                        strokeDasharray={`${circumference * SPINNER_ARC_SIZE} ${circumference * (1 - SPINNER_ARC_SIZE)}`}
+                        strokeLinecap="round"
+                    />
+                )}
+
+                {/* Indeterminate wave - Google Loader style animation */}
+                {showIndeterminateSpinner && indeterminateAnimation === 'wave' && (
+                    <circle
+                        {...circleBaseProps}
+                        className="origin-center animate-progress-wave"
+                        stroke={strokeColor}
+                        strokeLinecap="round"
+                    />
+                )}
+
+                {/* Colored progress circle - tied to progress value (determinate mode) */}
+                {showProgressArc && (
+                    <circle
+                        {...circleBaseProps}
+                        className="origin-center -rotate-90 transition-[stroke-dashoffset_0.5s_ease-in-out_0.3s,stroke_0.3s_ease-in-out]"
+                        stroke={progressCircleColor}
+                        strokeDasharray={circumference}
+                        strokeDashoffset={progressOffset}
+                        strokeLinecap="round"
+                    />
+                )}
+
+                {/* Center icon content */}
+                {!isShowingCompletion && (
+                    <foreignObject
+                        height={ICON_CONTAINER_SIZE}
+                        width={ICON_CONTAINER_SIZE}
+                        x={iconViewBoxOffset}
+                        y={iconViewBoxOffset}
+                    >
+                        <div className="flex h-full w-full items-center justify-center">
+                            {centerIcon || (
+                                <svg
+                                    fill="none"
+                                    height={ICON_CONTAINER_SIZE}
+                                    viewBox={`0 0 ${VIEWBOX_SIZE} ${VIEWBOX_SIZE}`}
+                                    width={ICON_CONTAINER_SIZE}
+                                    xmlns="http://www.w3.org/2000/svg"
+                                >
+                                    <path
+                                        className="transition-[fill_0.3s_ease-in-out]"
+                                        d="M21.4015 16.5893C21.3406 16.6504 21.2681 16.699 21.1883 16.7321C21.1086 16.7652 21.0231 16.7823 20.9367 16.7823C20.8503 16.7823 20.7648 16.7652 20.685 16.7321C20.6053 16.699 20.5328 16.6504 20.4718 16.5893L17.656 13.7734V21.8125C17.656 21.9865 17.5868 22.1534 17.4638 22.2765C17.3407 22.3996 17.1738 22.4687 16.9997 22.4687C16.8257 22.4687 16.6588 22.3996 16.5357 22.2765C16.4126 22.1534 16.3435 21.9865 16.3435 21.8125V13.7734L13.5265 16.5893C13.4032 16.7125 13.236 16.7818 13.0617 16.7818C12.8873 16.7818 12.7201 16.7125 12.5968 16.5893C12.4736 16.466 12.4043 16.2988 12.4043 16.1244C12.4043 15.9501 12.4736 15.7829 12.5968 15.6596L16.5343 11.7221C16.5953 11.6609 16.6678 11.6123 16.7475 11.5792C16.8273 11.5461 16.9128 11.5291 16.9992 11.5291C17.0856 11.5291 17.1711 11.5461 17.2508 11.5792C17.3306 11.6123 17.4031 11.6609 17.464 11.7221L21.4015 15.6596C21.4627 15.7205 21.5113 15.793 21.5444 15.8728C21.5775 15.9525 21.5945 16.038 21.5945 16.1244C21.5945 16.2108 21.5775 16.2963 21.5444 16.3761C21.5113 16.4558 21.4627 16.5283 21.4015 16.5893Z"
+                                        fill={arrowColor}
+                                    />
+                                </svg>
+                            )}
+                        </div>
+                    </foreignObject>
+                )}
+
+                {/* Completion CheckCircle */}
+                {isShowingCompletion && (
+                    <foreignObject
+                        height={ICON_CONTAINER_SIZE}
+                        width={ICON_CONTAINER_SIZE}
+                        x={iconViewBoxOffset}
+                        y={iconViewBoxOffset}
+                    >
+                        <div className="flex h-full w-full animate-progress-icon-fade-in items-center justify-center">
+                            <CheckCircle
+                                color="success"
+                                size="md"
+                                style="fill"
+                            />
+                        </div>
+                    </foreignObject>
+                )}
+            </svg>
+        </span>
+    );
+};
+
+ProgressCircle.displayName = 'ProgressCircle';

package/src/ProgressCircle/hooks/useProgressStatusTransitions.ts

@@ -0,0 +1,49 @@
+import { useEffect, useState } from 'react';
+
+type ProgressCircleStatus = 'pending' | 'progressing' | 'complete' | 'indeterminate';
+
+/**
+ * Manages the animation state for the ProgressCircle component.
+ *
+ * Handles two animation concerns:
+ * 1. `animateToSolidCircle` - Controls the transition from dashed to solid circle
+ * 2. `isShowingCompletion` - Controls whether to show the completion checkmark
+ *
+ * @param status - The current status of the progress circle
+ * @returns Animation state flags for the component
+ */
+export const useProgressStatusTransitions = (status: ProgressCircleStatus) => {
+    const isComplete = status === 'complete';
+    const isProgressing = status === 'progressing';
+    const isIndeterminate = status === 'indeterminate';
+
+    // State to control animation trigger
+    const [animateToSolidCircle, setAnimateToSolidCircle] = useState(false);
+    // State to track completion animation
+    const [isShowingCompletion, setIsShowingCompletion] = useState(false);
+
+    // Trigger completion animation when status changes to/from 'complete'
+    useEffect(() => {
+        setIsShowingCompletion(isComplete);
+    }, [isComplete]);
+
+    // Trigger animation when status changes to progressing, complete, or indeterminate
+    useEffect(() => {
+        if (isProgressing || isComplete || isIndeterminate) {
+            // Small delay to ensure element is mounted before animating
+            const timer = setTimeout(() => {
+                setAnimateToSolidCircle(true);
+            }, 10);
+
+            return () => {
+                clearTimeout(timer);
+            };
+        }
+
+        setAnimateToSolidCircle(false);
+
+        return undefined;
+    }, [isComplete, isIndeterminate, isProgressing]);
+
+    return { animateToSolidCircle, isShowingCompletion };
+};

package/src/ProgressCircle/utils/progressCircle.constants.ts

@@ -0,0 +1,27 @@
+// SVG dimensions and styling constants
+export const VIEWBOX_SIZE = 34;
+export const CIRCLE_RADIUS = 11.25;
+export const CIRCLE_CENTER = 17;
+export const STROKE_WIDTH = 1.5;
+export const ICON_CONTAINER_SIZE = 34;
+export const DASHED_PATTERN = '4 4';
+
+// Outer circle sizes matching IconButton
+export const progressCircleOuterSizes = {
+    lg: 54,
+    md: 42,
+    sm: 34,
+} as const;
+
+// Animation calculation constants
+export const WAVE_ARC_SIZE = 0.75;
+export const WAVE_OFFSET = 0.125;
+export const SPINNER_ARC_SIZE = 0.25;
+
+// Base props for all circle SVG elements (derived from constants above)
+export const circleBaseProps = {
+    cx: CIRCLE_CENTER,
+    cy: CIRCLE_CENTER,
+    r: CIRCLE_RADIUS,
+    strokeWidth: STROKE_WIDTH,
+} as const;

package/src/ProgressSteps/ProgressSteps.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { cn } from '@evolve.ui/theme-system';
+import { ReactNode, useCallback } from 'react';
+
+import { Check } from '../Icons';
+import { IconComponent } from '../Icons/IconBase';
+import { BodySecondary, Caption, LabelStrong } from '../Typography/Text/Text';
+
+export type StepItem = {
+    StepIcon?: IconComponent;
+    description?: ReactNode;
+    isCompleted: boolean;
+    label: ReactNode;
+};
+
+export type ProgressStepsProps = {
+    /** Used for passing styles down to the StepsComplete container. */
+    readonly className?: string;
+    /** Indicates the current step */
+    readonly currentStep?: number;
+    /** Adds a data-testid attribute to the dom element, used for end to end testing. */
+    readonly 'data-testid'?: string;
+    /** when true, the step labels will not be shown */
+    readonly hideStepLabels?: boolean;
+    /** when true, the steps will be displayed as numbers, overriding the icon */
+    readonly isNumeric?: boolean;
+    /** Array of steps */
+    readonly steps: StepItem[];
+};
+
+export const ProgressSteps = ({
+    className,
+    currentStep = 0,
+    'data-testid': testid = 'progressSteps',
+    hideStepLabels = false,
+    isNumeric = false,
+    steps = [],
+}: ProgressStepsProps) => {
+    if (!steps.length) {
+        throw new Error('Missing or empty step items.');
+    }
+
+    const buildProgressStep = useCallback(
+        (step: StepItem, index: number) => {
+            const StepIcon = step.StepIcon ?? null;
+            const thisStep = index + 1;
+            const isCurrentStep = currentStep === thisStep;
+
+            return (
+                <div
+                    className="relative"
+                    key={`progress-index-${thisStep}`}
+                >
+                    {!step.isCompleted || isCurrentStep ? (
+                        <div
+                            className={cn(
+                                'm-[3px] h-md w-md rounded-lg border-[1px] border-border-selected text-3xl text-primary-50',
+                                {
+                                    'bg-icon-secondary': isCurrentStep,
+                                }
+                            )}
+                        >
+                            {isNumeric ? (
+                                <LabelStrong
+                                    className={cn(
+                                        'block w-full text-center',
+                                        isCurrentStep ? 'text-text-inverse' : 'text-icon-secondary'
+                                    )}
+                                >
+                                    {thisStep}
+                                </LabelStrong>
+                            ) : (
+                                StepIcon && (
+                                    <StepIcon
+                                        className="m-[4px]"
+                                        color={isCurrentStep ? 'inverse' : 'secondary'}
+                                        size="xs"
+                                        style="bold"
+                                    />
+                                )
+                            )}
+                        </div>
+                    ) : (
+                        <div className="m-[3px] h-md w-md rounded-lg border-[1px] border-border-selected bg-icon-secondary p-[4px] text-3xl">
+                            <Check
+                                color="inverse"
+                                size="xs"
+                                style="bold"
+                            />
+                        </div>
+                    )}
+                </div>
+            );
+        },
+        [currentStep, isNumeric]
+    );
+
+    return (
+        <div
+            className={cn('relative inline-flex w-full flex-row justify-between pb-10', className)}
+            data-hui-id="ProgressSteps"
+            data-testid={testid}
+        >
+            {steps.map((step: StepItem, index: number) => {
+                const afterBorderColor =
+                    currentStep >= index + 1 ? 'after:border-border-selected' : 'after:border-border-secondary';
+                const beforeBorderColor =
+                    currentStep >= index ? 'before:border-border-selected' : 'before:border-border-secondary';
+                return (
+                    <div
+                        className={cn(
+                            'relative flex w-[140px] flex-shrink flex-grow flex-col items-center justify-start px-xs',
+                            index < steps.length - 1 && [
+                                "after:content-['']",
+                                'after:absolute',
+                                'after:left-[calc(50%+15px)]',
+                                'after:right-0',
+                                'after:top-[15px]',
+                                'after:w-[50%]',
+                                'after:h-[2px]',
+                                'after:border-b-[2px]',
+                                afterBorderColor,
+                                'after:pointer-events-none',
+                            ],
+                            index > 0 && [
+                                "before:content-['']",
+                                'before:absolute',
+                                'before:right-[calc(50%+15px)]',
+                                'before:top-[15px]',
+                                'before:w-[50%]',
+                                'before:h-[2px]',
+                                'before:border-b-[2px]',
+                                beforeBorderColor,
+                                'before:pointer-events-none',
+                            ]
+                        )}
+                        key={index}
+                    >
+                        {buildProgressStep(step, index)}
+                        {!hideStepLabels && (
+                            <BodySecondary className="mt-xs inline-block text-center">{step.label}</BodySecondary>
+                        )}
+
+                        {step.description && (
+                            <Caption
+                                className="text-center"
+                                color="secondary"
+                            >
+                                {step.description}
+                            </Caption>
+                        )}
+                    </div>
+                );
+            })}
+        </div>
+    );
+};
+
+ProgressSteps.displayName = 'ProgressSteps';