@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/Confetti/Confetti.tsx

@@ -0,0 +1,270 @@
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+// Physics constants are authored at 60 fps; frameScale normalizes them to any refresh rate.
+const TARGET_FRAME_MS = 1000 / 60;
+const DEFAULT_PARTICLE_COUNT = 150;
+const GRAVITY = 0.28; // downward acceleration (CSS px / frame² at 60fps)
+const LAUNCH_SPEED_MIN = 10; // minimum initial upward velocity (CSS px / frame at 60fps)
+const LAUNCH_SPEED_MAX = 22; // maximum initial upward velocity (CSS px / frame at 60fps)
+const LATERAL_SPREAD = 10; // horizontal velocity range (±5 CSS px / frame at 60fps)
+const SIZE_MIN = 6; // minimum particle size in CSS px
+const SIZE_MAX = 12; // maximum particle size in CSS px
+const FADE_DESCENT_THRESHOLD = 0.5; // vy at which opacity begins to drop (px/frame at 60fps)
+
+/**
+ * Brand color palette drawn from the Default theme's generated token steps.
+ * Matches success, warning, surface, primary, and critical token families
+ * (`--color-*` step values from `@evolve.ui/theme-system` Default brand).
+ */
+const DEFAULT_COLORS = {
+    success800: '#0B5125',
+    success600: '#12823B',
+    warning600: '#AE5F05',
+    warning300: '#FAAF57',
+    surface50: '#FFFFFF',
+    primary200: '#B8C3D8',
+    critical200: '#F4BDBD',
+} as const;
+
+type DefaultColorPalette = typeof DEFAULT_COLORS;
+type ColorKeys = keyof DefaultColorPalette;
+
+export type ConfettiHandle = {
+    /** Trigger a confetti burst across the bottom of the viewport. Re-calling while animating adds particles to the existing burst. */
+    fire: () => void;
+};
+
+/**
+ * Props for the Confetti component
+ */
+type Props = {
+    /** Override the default brand color palette
+     Allows passing a partial set of default colors, OR any custom string map.*/
+    colors?: Partial<Record<ColorKeys, string>> & Record<string, string>;
+    /** Called when the animation loop completes */
+    onComplete?: () => void;
+    /** Number of particles per burst. Default: 150 */
+    particleCount?: number;
+};
+
+type Particle = {
+    color: string;
+    /** Per-particle air resistance coefficient (0.94–0.98) for organic scattering */
+    drag: number;
+    /** Per-particle opacity reduction rate for varied fadeout timing */
+    fadeSpeed: number;
+    opacity: number;
+    rotation: number;
+    rotationSpeed: number;
+    /** Oscillation frequency for the 3D tumble effect (radians per ms) */
+    tumbleFrequency: number;
+    shape: 'circle' | 'rect';
+    size: number;
+    vx: number;
+    vy: number;
+    x: number;
+    y: number;
+};
+
+/**
+ * Resizes the canvas buffer to match physical device pixels and returns the
+ * scaled context. Setting canvas.width/height resets all transforms, so the
+ * Device Pixel Ratio (DPR) scale is safe to reapply immediately after.
+ */
+const setupCanvas = (canvas: HTMLCanvasElement): CanvasRenderingContext2D | null => {
+    const devicePixelRatio = window.devicePixelRatio ?? 1;
+    canvas.width = window.innerWidth * devicePixelRatio;
+    canvas.height = window.innerHeight * devicePixelRatio;
+    const canvasContext = canvas.getContext('2d');
+    canvasContext?.scale(devicePixelRatio, devicePixelRatio);
+    return canvasContext;
+};
+
+const createParticle = (colors: Record<string, string> = DEFAULT_COLORS): Particle => {
+    const palette = Object.values(colors);
+    // Fallback to default colors if someone passed an empty object {}
+    const activePalette = palette.length > 0 ? palette : Object.values(DEFAULT_COLORS);
+    const chosenColor = activePalette[Math.floor(Math.random() * activePalette.length)];
+
+    return {
+        color: chosenColor,
+        drag: Math.random() * 0.04 + 0.94,
+        fadeSpeed: Math.random() * 0.008 + 0.006,
+        opacity: 1,
+        rotation: Math.random() * Math.PI,
+        rotationSpeed: (Math.random() - 0.5) * 0.15,
+        tumbleFrequency: Math.random() * 0.08 + 0.04,
+        shape: Math.random() < 0.5 ? 'rect' : 'circle',
+        size: Math.random() * (SIZE_MAX - SIZE_MIN) + SIZE_MIN,
+        vx: (Math.random() - 0.5) * LATERAL_SPREAD,
+        vy: -(Math.random() * (LAUNCH_SPEED_MAX - LAUNCH_SPEED_MIN) + LAUNCH_SPEED_MIN),
+        x: Math.random() * window.innerWidth,
+        y: window.innerHeight + 10,
+    };
+};
+
+/**
+ * Canvas-based confetti burst component with an imperative `fire()` API.
+ *
+ * Renders a fixed, pointer-events-none overlay canvas and fires a branded
+ * particle burst from across the bottom of the viewport on demand. Re-triggerable
+ * while animating (accumulates particles). Cleans up the Request Animation Frame (RAF) loop and resize
+ * listener on unmount.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<ConfettiHandle>(null);
+ * ref.current?.fire();
+ * return <Confetti ref={ref} />;
+ * ```
+ */
+export const Confetti = forwardRef<ConfettiHandle, Props>(
+    ({ colors = DEFAULT_COLORS, onComplete, particleCount = DEFAULT_PARTICLE_COUNT }, ref) => {
+        const canvasRef = useRef<HTMLCanvasElement>(null);
+        const canvasContextRef = useRef<CanvasRenderingContext2D | null>(null);
+        const particlesRef = useRef<Particle[]>([]);
+        const animationFrameRef = useRef<number | null>(null);
+        const lastTimestampRef = useRef<number>(0);
+
+        // Clean SSR Guard: Component returns null on server evaluation, flips safely on client mount.
+        const [mounted, setMounted] = useState(false);
+
+        const onCompleteRef = useRef(onComplete);
+        onCompleteRef.current = onComplete;
+
+        // tickRef holds the animation loop function in a ref so that:
+        //  1. The loop can call itself recursively via requestAnimationFrame.
+        //  2. If props change mid-animation, the loop automatically uses the
+        //     latest values on the next frame without needing to restart.
+        const tickRef = useRef<(timestamp: number) => void>(() => {});
+        tickRef.current = (timestamp: number) => {
+            const canvasContext = canvasContextRef.current;
+            if (!canvasContext) {
+                return;
+            }
+
+            // How many "60fps frames worth" of time has passed since the last tick.
+            // At 60Hz this is ~1.0; at 120Hz it's ~0.5 — physics are scaled accordingly
+            // so the animation runs at the same real-world speed on any display.
+            // Capped at 2.0 so a long tab-switch pause doesn't make particles jump.
+            const frameScale =
+                lastTimestampRef.current === 0
+                    ? 1
+                    : Math.min((timestamp - lastTimestampRef.current) / TARGET_FRAME_MS, 2);
+            lastTimestampRef.current = timestamp;
+
+            canvasContext.clearRect(0, 0, window.innerWidth, window.innerHeight);
+
+            particlesRef.current = particlesRef.current.filter((p) => p.opacity > 0 && p.y < window.innerHeight + 50);
+
+            for (const particle of particlesRef.current) {
+                // Move the particle: apply drag, gravity, then update position.
+                // Math.pow(drag, frameScale) keeps drag rate consistent at any refresh rate.
+                const dragFactor = Math.pow(particle.drag, frameScale);
+                particle.vx *= dragFactor;
+                particle.vy *= dragFactor;
+                particle.vy += GRAVITY * frameScale;
+                particle.x += particle.vx * frameScale;
+                particle.y += particle.vy * frameScale;
+                particle.rotation += particle.rotationSpeed * frameScale;
+
+                // Only start fading once the particle has peaked and is falling.
+                if (particle.vy > FADE_DESCENT_THRESHOLD) {
+                    particle.opacity -= particle.fadeSpeed * frameScale;
+                }
+
+                // Squash the shape along one or both axes using sin/cos of real time.
+                // This fakes a 3D tumbling look. Using real time (not frame count)
+                // keeps the tumble speed the same on any display refresh rate.
+                const tumbleY = Math.sin(timestamp * particle.tumbleFrequency * 0.05);
+
+                canvasContext.save();
+                canvasContext.translate(particle.x, particle.y);
+                canvasContext.rotate(particle.rotation);
+                canvasContext.globalAlpha = Math.max(0, particle.opacity);
+                canvasContext.fillStyle = particle.color;
+
+                if (particle.shape === 'circle') {
+                    canvasContext.scale(1, tumbleY); // squash on Y only — looks like a spinning coin
+                    canvasContext.beginPath();
+                    canvasContext.arc(0, 0, particle.size / 2, 0, Math.PI * 2);
+                    canvasContext.fill();
+                } else {
+                    const tumbleX = Math.cos(timestamp * particle.tumbleFrequency * 0.03);
+                    canvasContext.scale(tumbleX, tumbleY); // squash on both axes — looks like fluttering paper
+                    canvasContext.fillRect(-particle.size / 2, -particle.size / 2, particle.size, particle.size);
+                }
+
+                canvasContext.restore();
+            }
+
+            if (particlesRef.current.length > 0) {
+                animationFrameRef.current = requestAnimationFrame(tickRef.current);
+            } else {
+                animationFrameRef.current = null;
+                lastTimestampRef.current = 0;
+                onCompleteRef.current?.();
+            }
+        };
+
+        useImperativeHandle(ref, () => ({
+            fire() {
+                if (!canvasRef.current) {
+                    return;
+                }
+
+                for (let i = 0; i < particleCount; i++) {
+                    particlesRef.current.push(createParticle(colors));
+                }
+
+                if (animationFrameRef.current === null) {
+                    lastTimestampRef.current = 0;
+                    animationFrameRef.current = requestAnimationFrame(tickRef.current);
+                }
+            },
+        }));
+
+        useEffect(() => {
+            setMounted(true);
+
+            const canvas = canvasRef.current;
+            if (!canvas) {
+                return;
+            }
+
+            canvasContextRef.current = setupCanvas(canvas);
+
+            const handleResize = () => {
+                if (canvasRef.current) {
+                    canvasContextRef.current = setupCanvas(canvasRef.current);
+                }
+            };
+
+            window.addEventListener('resize', handleResize);
+            return () => {
+                window.removeEventListener('resize', handleResize);
+                if (animationFrameRef.current !== null) {
+                    window.cancelAnimationFrame(animationFrameRef.current);
+                }
+            };
+        }, [mounted]); // Depend on mounted initialization so it properly captures the canvas element once attached to the DOM
+
+        if (!mounted) {
+            return null;
+        }
+
+        return createPortal(
+            <canvas
+                aria-hidden="true"
+                className="pointer-events-none fixed inset-0 z-[9999] h-screen w-screen"
+                data-hui-id="Confetti"
+                data-testid="confetti"
+                ref={canvasRef}
+            />,
+            document.body
+        );
+    }
+);
+
+Confetti.displayName = 'Confetti';

package/src/Confetti/index.ts

@@ -0,0 +1,2 @@
+export { Confetti } from './Confetti';
+export type { ConfettiHandle } from './Confetti';

package/src/ContentPager/ContentPager.tsx

@@ -0,0 +1,189 @@
+import { cn } from '@evolve.ui/theme-system';
+import { animated, useSpring, useTransition } from '@react-spring/web';
+import { atom, useSetAtom } from 'jotai';
+import { ComponentProps, FC, HTMLProps, ReactElement, useEffect, useMemo, useRef, useState } from 'react';
+import useMeasure from 'react-use-measure';
+
+import { nodeEnv } from '../utils/nodeEnv';
+import { Page } from './components/Page';
+
+// react-spring 9.7.5's AnimatedComponent props drop `children` under TypeScript 6;
+// runtime behavior is unchanged — re-widen with a typed alias.
+type AnimatedDivProps = Omit<HTMLProps<HTMLDivElement>, 'style'> & { style?: object };
+const AnimatedDiv = animated.div as unknown as FC<AnimatedDivProps>;
+
+export const currentPageAtom = atom<string>('');
+
+type PagerProps = {
+    /** Page components */
+    children: ReactElement<ComponentProps<typeof Page>>[];
+    /** Custom styling for the outermost ContentPager containing element */
+    className?: string;
+    /** The currently visible page */
+    currentPage: string;
+    /** Adds a data-testid attribute to the dom element, used for end to end testing. */
+    'data-testid'?: string;
+    /** A callback to run when animation has completed. Useful for focusing.*/
+    onTransitionEnd?: () => void;
+};
+
+export const ContentPager = ({
+    children,
+    className,
+    currentPage,
+    'data-testid': testId = 'content-pager',
+    onTransitionEnd,
+}: PagerProps) => {
+    // Add state for modal content height detection
+    const [initialPage, setInitialPage] = useState<string>(currentPage);
+    const [modalContentHeight, setModalContentHeight] = useState(0);
+    const isTestEnv = nodeEnv === 'test';
+    const isInitialRender = useRef(true);
+
+    const setCurrentPage = useSetAtom(currentPageAtom);
+
+    const [ref, { height, width }] = useMeasure();
+
+    const currentPageIndex = useMemo(
+        () => children.findIndex((page) => page.props.name === currentPage),
+        [children, currentPage]
+    );
+    const currentPageComponent = useMemo(() => children[currentPageIndex], [children, currentPageIndex]);
+
+    const [previousPageIndex, setPreviousPageIndex] = useState(currentPageIndex);
+
+    const containerAnimatedStyles = useSpring({
+        config: {
+            // Increase friction for less oscillation
+            friction: 32,
+            // Prevent spring from overshooting its target, eliminating final bounce
+            overshootClamping: true,
+            // End animation sooner when displacement is below this threshold (increased from 0.01)
+            restDisplacementThreshold: 0.1,
+            // End animation sooner when speed drops below this threshold (increased from 2)
+            restSpeedThreshold: 10,
+            // Increase tension slightly for snappier animations
+            tension: 280,
+        },
+        height: isInitialRender.current
+            ? modalContentHeight
+            : initialPage === currentPage && modalContentHeight !== 0
+              ? modalContentHeight
+              : height,
+        immediate: isTestEnv || isInitialRender.current,
+    });
+
+    const { fromTransform, leaveTransform } = useMemo(() => {
+        const rightTransform = `translate(${width}px)`;
+        const leftTransform = `translate(-${width}px)`;
+        const fromTransform = currentPageIndex > previousPageIndex ? rightTransform : leftTransform;
+        const leaveTransform = currentPageIndex > previousPageIndex ? leftTransform : rightTransform;
+
+        return { fromTransform, leaveTransform };
+    }, [currentPageIndex, previousPageIndex, width]);
+
+    useEffect(() => {
+        if (initialPage === '') {
+            return;
+        }
+
+        if (initialPage !== currentPage) {
+            setInitialPage('');
+            setModalContentHeight(0);
+        }
+        if (isInitialRender.current) {
+            window.requestAnimationFrame(() => {
+                isInitialRender.current = false;
+            });
+        }
+    }, [currentPage, currentPageIndex, initialPage]);
+
+    // Ensure that modal content height is detected as it has issues with the transition
+    useEffect(() => {
+        if (currentPage === initialPage) {
+            const modalElement = document.querySelector('[data-hui-id="Modal"]');
+            const pageElement = document.querySelector(
+                '[data-hui-id="ContentPager"] [data-page-name]'
+            ) as HTMLElement | null;
+
+            if (modalElement && pageElement) {
+                setModalContentHeight(pageElement.scrollHeight + 1);
+            }
+        }
+    }, [currentPage, initialPage, height]);
+
+    // Keep the current page atom in sync immediately, so portal actions can resolve visibility on first render
+    useEffect(() => {
+        setCurrentPage(currentPage);
+    }, [currentPage, setCurrentPage]);
+
+    const transitions = useTransition(
+        [
+            {
+                currentPage,
+                currentPageComponent,
+            },
+        ],
+        {
+            enter: {
+                opacity: 1,
+                transform: 'translate(0px)',
+            },
+            from: {
+                opacity: 0,
+                transform: fromTransform,
+            },
+            immediate: isInitialRender.current,
+            initial: {
+                opacity: 1,
+                transform: 'translate(0px)',
+            },
+            keys: (page) => page.currentPage,
+            leave: {
+                opacity: 0,
+                transform: leaveTransform,
+            },
+            onRest: () => {
+                setPreviousPageIndex(currentPageIndex);
+                if (onTransitionEnd) {
+                    onTransitionEnd();
+                }
+            },
+            onStart: () => {
+                setCurrentPage(currentPage);
+            },
+        }
+    );
+
+    return (
+        <AnimatedDiv
+            className={cn('relative w-full overflow-hidden', className)}
+            data-hui-id="ContentPager"
+            data-testid={testId}
+            style={{
+                ...containerAnimatedStyles,
+                height: containerAnimatedStyles.height,
+            }}
+        >
+            {transitions(({ ...style }, page) => (
+                <AnimatedDiv
+                    className={cn('absolute left-0 right-0 h-full')}
+                    style={{
+                        ...style,
+                        opacity: style.opacity,
+                        position: 'absolute',
+                    }}
+                >
+                    <div
+                        data-page-name={page.currentPage}
+                        ref={ref}
+                    >
+                        {page.currentPageComponent}
+                    </div>
+                </AnimatedDiv>
+            ))}
+        </AnimatedDiv>
+    );
+};
+
+export { Page };

package/src/ContentPager/components/Page.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+type PageProps = {
+    /** Page content */
+    children: React.ReactNode;
+    /** className __ALL__ exported components pass through a classname to the outermost component */
+    className?: string;
+    /** Adds a data-testid attribute to the dom element, used for end to end testing. */
+    'data-testid'?: string;
+    /** A unique page name, used by the parent <ContentPager /> for moving between pages */
+    name: string;
+};
+
+export const Page = ({ children, className, 'data-testid': testId = 'pager-content-page' }: PageProps) => {
+    return (
+        <div
+            className={className}
+            data-testid={testId}
+            id="content-pager-page"
+        >
+            {children}
+        </div>
+    );
+};

package/src/CookieConsent/components/CookieCategoryRow/CookieCategoryRow.tsx

@@ -0,0 +1,30 @@
+import { memo } from 'react';
+
+import { ToggleSwitch } from '../../../ToggleSwitch/ToggleSwitch';
+import { BodySecondary, Caption, LabelStrong } from '../../../Typography/Text/Text';
+
+type Props = {
+    description: string;
+    isToggled: boolean;
+    label: string;
+    onToggleChange?: () => void;
+    required?: boolean;
+};
+
+export const CookieCategoryRow = memo(({ description, isToggled, label, onToggleChange, required }: Props) => (
+    <div className="flex flex-col gap-2xs border-b border-border-secondary py-sm">
+        <div className="flex h-[22px] items-center justify-between">
+            <LabelStrong>{label}</LabelStrong>
+            {required ? (
+                <BodySecondary className="text-text-primary">Required</BodySecondary>
+            ) : (
+                <ToggleSwitch
+                    aria-label={label}
+                    isToggled={isToggled}
+                    onToggleChange={onToggleChange}
+                />
+            )}
+        </div>
+        <Caption className="text-text-secondary">{description}</Caption>
+    </div>
+));

package/src/CookieConsent/components/CookieConsent/CookieConsent.tsx

@@ -0,0 +1,74 @@
+import { forwardRef, useImperativeHandle } from 'react';
+
+import type { ConsentCategories, CookieCategoryConfig, CookieConsentTracking } from '../../types/cookieConsent.types';
+
+import { useCookieConsentState } from '../../hooks/useCookieConsentState';
+import { CookieConsentBanner } from '../CookieConsentBanner/CookieConsentBanner';
+import { CookieConsentModal } from '../CookieConsentModal/CookieConsentModal';
+
+const DEFAULT_TOAST_MESSAGE = 'Your privacy preferences have been saved.';
+
+type Props = {
+    categories?: CookieCategoryConfig[];
+    /**
+     * Controlled consent state. When provided, an external consent-management
+     * platform (CMP) owns the consent state: internal localStorage persistence
+     * is bypassed and the banner is never auto-shown. Sync user changes back to
+     * the CMP via `onConsentChange`.
+     */
+    consent?: ConsentCategories;
+    onConsentChange?: (consent: ConsentCategories) => void;
+    /** localStorage key used to persist consent in uncontrolled mode (default `'hui-cookie-consent'`). */
+    storageKey?: string;
+    toastMessage?: string;
+    tracking?: CookieConsentTracking;
+};
+
+export type CookieConsentHandle = {
+    openModal: () => void;
+};
+
+/**
+ * Custom cookie consent UI (banner + preferences modal).
+ *
+ * Renders the consent banner and modal. By default consent is persisted to
+ * localStorage via `useCookieConsentState`; pass the `consent` prop to let an
+ * external consent-management platform own the state instead. Exposes
+ * `openModal()` through a ref for programmatic access (e.g. footer
+ * "Cookie Preferences" link).
+ */
+export const CookieConsent = forwardRef<CookieConsentHandle, Props>(
+    (
+        { categories, consent, onConsentChange, storageKey, toastMessage = DEFAULT_TOAST_MESSAGE, tracking } = {},
+        ref
+    ) => {
+        const state = useCookieConsentState({ consent, onConsentChange, storageKey, toastMessage, tracking });
+
+        useImperativeHandle(ref, () => ({ openModal: state.openModal }), [state.openModal]);
+
+        if (!state.showBanner && !state.showDialog) {
+            return null;
+        }
+
+        return (
+            <>
+                {state.showBanner && (
+                    <CookieConsentBanner
+                        isExiting={state.bannerExiting}
+                        onAnimationEnd={state.handleBannerAnimationEnd}
+                        onDismiss={state.handleOk}
+                        onOpenPreferences={state.openDialog}
+                    />
+                )}
+                <CookieConsentModal
+                    categories={categories}
+                    localConsent={state.localConsent}
+                    onClose={state.closeDialog}
+                    onSave={state.handleSavePreferences}
+                    onToggle={state.handleToggle}
+                    show={state.showDialog}
+                />
+            </>
+        );
+    }
+);

package/src/CookieConsent/components/CookieConsentBanner/CookieConsentBanner.tsx

@@ -0,0 +1,51 @@
+import { cn } from '@evolve.ui/theme-system';
+import { AnimationEvent, memo } from 'react';
+
+import { Button } from '../../../Button/Button';
+import { InlineButton } from '../../../Typography/InlineButton/InlineButton';
+import { BodySecondary } from '../../../Typography/Text/Text';
+
+type Props = {
+    isExiting: boolean;
+    onAnimationEnd: (e: AnimationEvent<HTMLDivElement>) => void;
+    onDismiss: () => void;
+    onOpenPreferences: () => void;
+};
+
+export const CookieConsentBanner = memo(({ isExiting, onAnimationEnd, onDismiss, onOpenPreferences }: Props) => (
+    <div
+        aria-label="Cookie consent"
+        className={cn(
+            'fixed inset-x-0 bottom-md z-[10300] mx-auto w-[calc(100%-48px)] max-w-[1200px] rounded-md border border-border-secondary bg-background-tertiary shadow-01',
+            isExiting ? 'animate-slideDown' : 'animate-slideUp'
+        )}
+        onAnimationEnd={onAnimationEnd}
+        role="region"
+    >
+        <div className="flex flex-col gap-xs p-sm smMin:flex-row smMin:items-center smMin:gap-md smMin:p-md">
+            <div className="min-w-0 flex-1">
+                <BodySecondary className="inline">
+                    We use cookies to improve your experience, to analyze website usage, and for marketing purposes.
+                </BodySecondary>
+                <InlineButton
+                    className="ml-2xs inline text-text-primary underline"
+                    onClick={onOpenPreferences}
+                    size="sm"
+                >
+                    Cookie preferences
+                </InlineButton>
+            </div>
+            <div className="shrink-0 self-end smMin:self-auto">
+                <Button
+                    className="min-w-[96px]"
+                    onClick={onDismiss}
+                    size="sm"
+                    style="neutral"
+                    variant="outlined"
+                >
+                    OK
+                </Button>
+            </div>
+        </div>
+    </div>
+));