@evolve.ui/core-components 1.0.0 → 1.1.0

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

@@ -0,0 +1,64 @@
+import { memo } from 'react';
+
+import { Button } from '../../../Button/Button';
+import { CloseButton, ModalActions, ModalContent, ModalHeader } from '../../../Modal/components';
+import { Modal } from '../../../Modal/Modal';
+import { BodySecondary, H2 } from '../../../Typography/Text/Text';
+import { ConsentCategories, CookieCategoryConfig, DEFAULT_COOKIE_CATEGORIES } from '../../types/cookieConsent.types';
+import { CookieCategoryRow } from '../CookieCategoryRow/CookieCategoryRow';
+
+type Props = {
+    categories?: CookieCategoryConfig[];
+    localConsent: ConsentCategories;
+    onClose: () => void;
+    onSave: () => void;
+    onToggle: (key: keyof ConsentCategories) => void;
+    show: boolean;
+};
+
+export const CookieConsentModal = memo(
+    ({ categories = DEFAULT_COOKIE_CATEGORIES, localConsent, onClose, onSave, onToggle, show }: Props) => (
+        <Modal
+            className="max-w-[588px]"
+            handleClose={onClose}
+            show={show}
+            type="composable"
+        >
+            <CloseButton />
+            <ModalHeader>
+                <H2>Cookie Preferences</H2>
+            </ModalHeader>
+            <ModalContent className="max-w-460px pb-sm">
+                <BodySecondary className="mb-sm">
+                    Our platform uses various types of cookies, each of which has a specific function. Manage your
+                    preferences below:
+                </BodySecondary>
+                <div className="border-b border-border-secondary pb-sm"></div>
+                <div className="flex flex-col">
+                    {categories.map((cat) => (
+                        <CookieCategoryRow
+                            description={cat.description}
+                            isToggled={cat.required ? true : localConsent[cat.key as keyof ConsentCategories]}
+                            key={cat.key}
+                            label={cat.label}
+                            onToggleChange={
+                                cat.required ? undefined : () => onToggle(cat.key as keyof ConsentCategories)
+                            }
+                            required={cat.required}
+                        />
+                    ))}
+                </div>
+            </ModalContent>
+            <ModalActions>
+                <Button
+                    onClick={onSave}
+                    size="md"
+                    style="primary"
+                    variant="filled"
+                >
+                    SAVE PREFERENCES
+                </Button>
+            </ModalActions>
+        </Modal>
+    )
+);

package/src/CookieConsent/hooks/useCookieConsent.ts

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import type { ConsentCategories, ConsentPayload } from '../types/cookieConsent.types';
+
+export const DEFAULT_CONSENT_STORAGE_KEY = 'hui-cookie-consent';
+
+const DEFAULT_CONSENT: ConsentCategories = {
+    marketing: false,
+    preferences: false,
+    statistics: false,
+};
+
+/**
+ * Reads a previously persisted consent payload from localStorage.
+ * Returns `undefined` during SSR, when nothing is stored, or when the stored
+ * value is corrupt/unparseable (corrupt values are treated as "no response yet"
+ * so the banner shows again rather than trusting bad data).
+ */
+const readStoredConsent = (storageKey: string): ConsentCategories | undefined => {
+    /* istanbul ignore next -- @preserve: SSR guard; a React test renderer always runs with a defined `window`, so this branch is unreachable under jest/jsdom. */
+    if (typeof window === 'undefined') {
+        return undefined;
+    }
+
+    let raw: string | null = null;
+    try {
+        raw = window.localStorage.getItem(storageKey);
+    } catch {
+        // localStorage can throw (e.g. disabled in the browser) — treat as no response.
+        return undefined;
+    }
+
+    if (!raw) {
+        return undefined;
+    }
+
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        if (
+            typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof (parsed as ConsentPayload).marketing === 'boolean' &&
+            typeof (parsed as ConsentPayload).preferences === 'boolean' &&
+            typeof (parsed as ConsentPayload).statistics === 'boolean'
+        ) {
+            const payload = parsed as ConsentPayload;
+            return {
+                marketing: payload.marketing,
+                preferences: payload.preferences,
+                statistics: payload.statistics,
+            };
+        }
+    } catch {
+        // Corrupt JSON — fall through to undefined.
+    }
+
+    return undefined;
+};
+
+/**
+ * Persists a consent payload to localStorage. No-ops during SSR or when
+ * localStorage is unavailable.
+ */
+const writeStoredConsent = (storageKey: string, categories: ConsentCategories) => {
+    /* istanbul ignore next -- @preserve: SSR guard; consent writes are user-triggered client-side actions and a React test renderer always has a defined `window`, so this branch is unreachable under jest/jsdom. */
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    const payload: ConsentPayload = { ...categories, necessary: true };
+
+    try {
+        window.localStorage.setItem(storageKey, JSON.stringify(payload));
+    } catch {
+        // localStorage unavailable — consent still applies for this session via state.
+    }
+};
+
+/** Params for the useCookieConsent hook. */
+export type UseCookieConsentParams = {
+    /**
+     * Controlled consent state. When provided, an external consent-management
+     * platform (CMP) owns the consent state: internal localStorage persistence
+     * is bypassed, the banner is never auto-shown, and consent reads reflect
+     * this value. Sync user changes back to the CMP via the component's
+     * `onConsentChange` callback.
+     */
+    consent?: ConsentCategories;
+    /** localStorage key used to persist consent in uncontrolled mode. */
+    storageKey?: string;
+};
+
+/**
+ * Low-level consent engine backed by localStorage.
+ *
+ * Uncontrolled (default) mode: on mount, reads any previously saved consent
+ * from localStorage. The banner is visible if and only if no stored consent
+ * exists. Action helpers (`acceptAll`, `declineAll`, `submitConsent`) persist
+ * the new consent payload and hide the banner.
+ *
+ * Controlled mode (`consent` param provided): an external CMP owns the state —
+ * nothing is read from or written to localStorage and the banner is never
+ * auto-shown; the preferences modal remains reachable via
+ * `CookieConsentHandle.openModal()`.
+ *
+ * Exposes `isBannerVisible`, current `consent` state, `hasResponse` (whether
+ * the user has already responded), and the action helpers.
+ */
+export const useCookieConsent = ({
+    consent: controlledConsent,
+    storageKey = DEFAULT_CONSENT_STORAGE_KEY,
+}: UseCookieConsentParams = {}) => {
+    const isControlled = controlledConsent !== undefined;
+
+    const [isBannerVisible, setIsBannerVisible] = useState(false);
+    const [internalConsent, setInternalConsent] = useState<ConsentCategories>(DEFAULT_CONSENT);
+    const [hasStoredResponse, setHasStoredResponse] = useState(false);
+
+    useEffect(() => {
+        if (isControlled) {
+            return;
+        }
+
+        const stored = readStoredConsent(storageKey);
+        if (stored) {
+            setInternalConsent(stored);
+            setHasStoredResponse(true);
+            setIsBannerVisible(false);
+        } else {
+            setIsBannerVisible(true);
+        }
+    }, [isControlled, storageKey]);
+
+    const applyConsent = useCallback(
+        (categories: ConsentCategories) => {
+            if (!isControlled) {
+                writeStoredConsent(storageKey, categories);
+            }
+            setInternalConsent(categories);
+            setHasStoredResponse(true);
+            setIsBannerVisible(false);
+        },
+        [isControlled, storageKey]
+    );
+
+    const acceptAll = useCallback(() => {
+        applyConsent({ marketing: true, preferences: true, statistics: true });
+    }, [applyConsent]);
+
+    const declineAll = useCallback(() => {
+        applyConsent(DEFAULT_CONSENT);
+    }, [applyConsent]);
+
+    const submitConsent = useCallback(
+        (categories: ConsentCategories) => {
+            applyConsent(categories);
+        },
+        [applyConsent]
+    );
+
+    return {
+        acceptAll,
+        consent: isControlled ? controlledConsent : internalConsent,
+        declineAll,
+        /** Whether the user has already responded (controlled mode counts as responded). */
+        hasResponse: isControlled || hasStoredResponse,
+        isBannerVisible,
+        submitConsent,
+    };
+};

package/src/CookieConsent/hooks/useCookieConsentState.ts

@@ -0,0 +1,142 @@
+import { AnimationEvent, useCallback, useEffect, useRef, useState } from 'react';
+
+import { toast } from '../../Toast';
+import {
+    ConsentCategories,
+    ConsentPayload,
+    ConsentSource,
+    UseCookieConsentStateParams,
+} from '../types/cookieConsent.types';
+import { useCookieConsent } from './useCookieConsent';
+
+const DEFAULT_LOCAL_CONSENT: ConsentCategories = {
+    marketing: true,
+    preferences: true,
+    statistics: true,
+};
+
+const buildConsentPayload = (consent: ConsentCategories): ConsentPayload => ({
+    ...consent,
+    necessary: true,
+});
+
+/**
+ * UI state manager for the CookieConsent component.
+ *
+ * Wraps `useCookieConsent` and owns banner/modal visibility, local consent
+ * toggle state, and all user interaction handlers (OK, save, toggle, open/close).
+ *
+ * Modal toggles default to all-ON (`DEFAULT_LOCAL_CONSENT`). When opening the
+ * modal, existing consent is read from the consent engine only if the user has
+ * already responded — before a response, consent initializes as all `false`,
+ * so we fall back to the all-ON default.
+ */
+export const useCookieConsentState = ({
+    consent: controlledConsent,
+    onConsentChange,
+    storageKey,
+    toastMessage,
+    tracking,
+}: UseCookieConsentStateParams) => {
+    const { acceptAll, consent, hasResponse, isBannerVisible, submitConsent } = useCookieConsent({
+        consent: controlledConsent,
+        storageKey,
+    });
+    const trackingRef = useRef(tracking);
+    trackingRef.current = tracking;
+
+    const [showBanner, setShowBanner] = useState(false);
+    const [bannerExiting, setBannerExiting] = useState(false);
+    const [showDialog, setShowDialog] = useState(false);
+    const [localConsent, setLocalConsent] = useState(DEFAULT_LOCAL_CONSENT);
+
+    const readCurrentConsent = useCallback(
+        (): ConsentCategories => (hasResponse ? consent : DEFAULT_LOCAL_CONSENT),
+        [consent, hasResponse]
+    );
+
+    useEffect(() => {
+        if (isBannerVisible) {
+            setShowBanner(true);
+            setBannerExiting(false);
+            trackingRef.current?.onBannerViewed?.();
+        }
+    }, [isBannerVisible]);
+
+    const openModal = useCallback(() => {
+        setLocalConsent(readCurrentConsent());
+        setShowDialog(true);
+    }, [readCurrentConsent]);
+
+    const handleBannerAnimationEnd = useCallback(
+        (e: AnimationEvent<HTMLDivElement>) => {
+            /* istanbul ignore next -- @preserve: `bannerExiting` is only ever set to false in this hook (faithful hammer parity), so the exit-animation cleanup branch is unreachable. Reported as latent dead code, not modified to preserve parity. */
+            if (bannerExiting && e.target === e.currentTarget) {
+                setShowBanner(false);
+                setBannerExiting(false);
+            }
+        },
+        [bannerExiting]
+    );
+
+    const openDialog = useCallback(() => {
+        setLocalConsent(readCurrentConsent());
+        setShowDialog(true);
+        setShowBanner(false);
+        setBannerExiting(false);
+        trackingRef.current?.onPreferencesOpened?.(ConsentSource.Banner);
+    }, [readCurrentConsent]);
+
+    const closeDialog = useCallback(() => {
+        setShowDialog(false);
+        trackingRef.current?.onPreferencesDismissed?.(ConsentSource.Modal);
+        if (isBannerVisible) {
+            setShowBanner(true);
+            setBannerExiting(false);
+        }
+    }, [isBannerVisible]);
+
+    const handleOk = useCallback(() => {
+        const allConsent: ConsentCategories = { marketing: true, preferences: true, statistics: true };
+        acceptAll();
+        onConsentChange?.(allConsent);
+        setShowBanner(false);
+        setBannerExiting(false);
+        toast('success', { title: toastMessage });
+        trackingRef.current?.onPreferencesSaved?.({
+            consent: buildConsentPayload(allConsent),
+            source: ConsentSource.Banner,
+        });
+    }, [acceptAll, onConsentChange, toastMessage]);
+
+    const handleSavePreferences = useCallback(() => {
+        submitConsent(localConsent);
+        onConsentChange?.(localConsent);
+        setShowDialog(false);
+        setShowBanner(false);
+        setBannerExiting(false);
+        toast('success', { title: toastMessage });
+        trackingRef.current?.onPreferencesSaved?.({
+            consent: buildConsentPayload(localConsent),
+            source: ConsentSource.Modal,
+        });
+    }, [localConsent, onConsentChange, submitConsent, toastMessage]);
+
+    const handleToggle = useCallback((key: keyof ConsentCategories) => {
+        setLocalConsent((prev) => ({ ...prev, [key]: !prev[key] }));
+    }, []);
+
+    return {
+        bannerExiting,
+        closeDialog,
+        handleBannerAnimationEnd,
+        handleOk,
+        handleSavePreferences,
+        handleToggle,
+        localConsent,
+        openDialog,
+        openModal,
+        showBanner,
+        showDialog,
+    };
+};

package/src/CookieConsent/index.ts

@@ -0,0 +1,16 @@
+// Components
+export { CookieConsent } from './components/CookieConsent/CookieConsent';
+export type { CookieConsentHandle } from './components/CookieConsent/CookieConsent';
+
+// Hooks
+export { useCookieConsent, DEFAULT_CONSENT_STORAGE_KEY } from './hooks/useCookieConsent';
+export type { UseCookieConsentParams } from './hooks/useCookieConsent';
+
+// Types
+export { ConsentSource, DEFAULT_COOKIE_CATEGORIES } from './types/cookieConsent.types';
+export type {
+    ConsentCategories,
+    CookieCategoryConfig,
+    CookieConsentTracking,
+    ConsentPayload,
+} from './types/cookieConsent.types';

package/src/CookieConsent/types/cookieConsent.types.ts

@@ -0,0 +1,79 @@
+/**
+ * The three non-essential consent categories managed by this component.
+ * `necessary` is excluded because it's always implicitly granted.
+ */
+export type ConsentCategories = {
+    marketing: boolean;
+    preferences: boolean;
+    statistics: boolean;
+};
+
+/** Full consent payload including the always-on `necessary` flag. */
+export type ConsentPayload = ConsentCategories & { necessary: true };
+
+/** Where the user interaction originated. */
+export enum ConsentSource {
+    Banner = 'banner',
+    Modal = 'modal',
+}
+
+/** Tracking callbacks for cookie consent analytics. */
+export type CookieConsentTracking = {
+    onBannerViewed?: () => void;
+    onPreferencesDismissed?: (source: ConsentSource) => void;
+    onPreferencesOpened?: (source: ConsentSource) => void;
+    onPreferencesSaved?: (payload: { consent: ConsentPayload; source: ConsentSource }) => void;
+};
+
+/** Params for the useCookieConsentState hook. */
+export type UseCookieConsentStateParams = {
+    /**
+     * Controlled consent state. When provided, an external consent-management
+     * platform owns the consent state and internal localStorage persistence is
+     * bypassed — sync changes back through `onConsentChange`.
+     */
+    consent?: ConsentCategories;
+    onConsentChange?: (consent: ConsentCategories) => void;
+    /** localStorage key used to persist consent in uncontrolled mode. */
+    storageKey?: string;
+    toastMessage: string;
+    tracking?: CookieConsentTracking;
+};
+
+/** Definition for a single row in the preferences modal. */
+export type CookieCategoryConfig = {
+    description: string;
+    /** Must match a `ConsentCategories` key, or `'necessary'` for the always-on row. */
+    key: keyof ConsentCategories | 'necessary';
+    label: string;
+    /** When `true`, the toggle is locked on and the user cannot opt out. */
+    required?: boolean;
+};
+
+export const DEFAULT_COOKIE_CATEGORIES: CookieCategoryConfig[] = [
+    {
+        description:
+            'Necessary cookies help make a website usable by enabling basic functions like page navigation and access to secure areas of the website. The website cannot function properly without these cookies.',
+        key: 'necessary',
+        label: 'Necessary',
+        required: true,
+    },
+    {
+        description:
+            'Preference cookies enable a website to remember information that changes the way the website behaves or looks, like your preferred language or the region that you are in.',
+        key: 'preferences',
+        label: 'Preferences',
+    },
+    {
+        description:
+            'Statistics cookies help website owners to understand how visitors interact with websites by collecting and reporting information anonymously.',
+        key: 'statistics',
+        label: 'Statistics',
+    },
+    {
+        description:
+            'Marketing cookies are used to track visitors across websites. The intention is to display ads that are relevant and engaging for the individual user and thereby more valuable for publishers and third party advertisers.',
+        key: 'marketing',
+        label: 'Marketing',
+    },
+];

package/src/CookieConsent/types/index.ts

@@ -0,0 +1,7 @@
+export type {
+    ConsentCategories,
+    CookieCategoryConfig,
+    CookieConsentTracking,
+    ConsentPayload,
+} from './cookieConsent.types';
+export { ConsentSource, DEFAULT_COOKIE_CATEGORIES } from './cookieConsent.types';

package/src/Countdown/Countdown.tsx

@@ -0,0 +1,161 @@
+import { useEffect } from 'react';
+
+import { BodySecondary, H3 } from '../Typography/Text/Text';
+import { CountdownFlashpoint } from './Countdown.types';
+import { useGetCountdown } from './hooks/useGetCountdown';
+
+/**
+ * @property completionTime Timestamp (in ms) for when the countdown will first reach zero
+ * @property flashpoint Amount of time left before the countdown turns red (signalling urgency)
+ * @property label Additional information for the countdown. *e.g.* 5d 23h **Until the event begins!**
+ * @property onComplete Called when the countdown reaches zero.
+ * @property preLabel Information shown before the countdown numbers. Will not be shown unless countdown is small
+ * @property small If true, all text (the countdown numbers and the label) will be the same size
+ * @property startTime Represents the time from which the countdown is counting down from
+ * @property timeLabels Used for internationalization, defaults to d/h/m/s, represents days/hours/minutes/seconds
+ */
+export type CountdownProps = {
+    /* Timestamp (in ms) for when the countdown will first reach zero */
+    completionTime: number;
+    // Amount of time left before the countdown turns red (signalling urgency)
+    flashpoint?: CountdownFlashpoint;
+    // If true, the countdown will always display with seconds included
+    forceSeconds?: boolean;
+    // If true, the countdown will always render in the urgent/critical color regardless of time remaining
+    forceUrgent?: boolean;
+    // Additional information for the countdown. *e.g.* 5d 23h **Until the event begins!**
+    label?: string;
+    // Called when the countdown reaches zero.
+    onComplete?: () => void;
+    // Information shown before the countdown numbers. Will not be shown unless countdown is small
+    preLabel?: string;
+    // If true, all text (the countdown numbers and the label) will be the same size
+    small?: boolean;
+    // Represents the time from which the countdown is counting down from
+    startTime?: number;
+    // Used for internationalization, defaults to d/h/m/s, represents days/hours/minutes/seconds
+    timeLabels?: {
+        days?: string;
+        hours?: string;
+        minutes?: string;
+        seconds?: string;
+    };
+};
+
+export const Countdown = ({
+    completionTime,
+    flashpoint,
+    forceSeconds,
+    forceUrgent,
+    label,
+    onComplete,
+    preLabel,
+    small,
+    startTime,
+    timeLabels,
+}: CountdownProps) => {
+    const {
+        daysUntilEnd,
+        hoursUntilEnd,
+        isUrgent: isUrgentFromFlashpoint,
+        minutesUntilEnd,
+        secondsUntilEnd,
+    } = useGetCountdown({
+        completionTime,
+        flashpoint,
+        forceSeconds,
+        startTime,
+    });
+
+    const isUrgent = forceUrgent || isUrgentFromFlashpoint;
+
+    const dayLabel = timeLabels?.days ?? 'd';
+    const hourLabel = timeLabels?.hours ?? 'h';
+    const minuteLabel = timeLabels?.minutes ?? 'm';
+    const secondLabel = timeLabels?.seconds ?? 's';
+
+    let primaryDurationValue = `${daysUntilEnd}${dayLabel}`;
+    let secondaryDurationValue: string | null = `${hoursUntilEnd}${hourLabel}`;
+    let altDurationValue = null;
+
+    // less than one day from end
+    if (daysUntilEnd === 0 && hoursUntilEnd !== 0) {
+        primaryDurationValue = `${hoursUntilEnd}${hourLabel}`;
+        secondaryDurationValue = `${minutesUntilEnd}${minuteLabel}`;
+        if (forceSeconds) {
+            altDurationValue = `${secondsUntilEnd}${secondLabel}`;
+        }
+    } else if (daysUntilEnd === 0 && hoursUntilEnd === 0 && minutesUntilEnd !== 0) {
+        primaryDurationValue = `${minutesUntilEnd}${minuteLabel}`;
+        secondaryDurationValue = `${secondsUntilEnd}${secondLabel}`;
+    } else if (daysUntilEnd === 0 && hoursUntilEnd === 0 && minutesUntilEnd === 0) {
+        primaryDurationValue = `${secondsUntilEnd}${secondLabel}`;
+        secondaryDurationValue = null;
+    }
+
+    useEffect(() => {
+        if (daysUntilEnd === 0 && hoursUntilEnd === 0 && minutesUntilEnd === 0 && secondsUntilEnd === 0) {
+            onComplete?.();
+        }
+    }, [daysUntilEnd, hoursUntilEnd, minutesUntilEnd, onComplete, secondsUntilEnd]);
+
+    if (small) {
+        return (
+            <div className="flex items-baseline whitespace-nowrap">
+                {Boolean(preLabel) && (
+                    <>
+                        <BodySecondary color={isUrgent ? 'critical' : 'primary'}>{preLabel}</BodySecondary>
+                        &nbsp;
+                    </>
+                )}
+                <BodySecondary color={isUrgent ? 'critical' : 'primary'}>{primaryDurationValue}</BodySecondary>
+                {secondaryDurationValue && (
+                    <>
+                        &nbsp;
+                        <BodySecondary color={isUrgent ? 'critical' : 'primary'}>
+                            {secondaryDurationValue}
+                        </BodySecondary>
+                    </>
+                )}
+                &nbsp;
+                {altDurationValue && (
+                    <>
+                        <BodySecondary color={isUrgent ? 'critical' : 'primary'}>{altDurationValue}</BodySecondary>
+                        &nbsp;
+                    </>
+                )}
+                <BodySecondary color={isUrgent ? 'critical' : 'primary'}>{label}</BodySecondary>
+            </div>
+        );
+    }
+
+    return (
+        <div className="flex items-baseline whitespace-nowrap">
+            <span className={`hui-text-h1 text-${isUrgent ? 'text-critical' : 'text-primary'}`}>
+                {primaryDurationValue}
+            </span>
+            {secondaryDurationValue && (
+                <>
+                    &nbsp;
+                    <span className={`hui-text-h1 text-${isUrgent ? 'text-critical' : 'text-primary'}`}>
+                        {secondaryDurationValue}
+                    </span>
+                </>
+            )}
+            {altDurationValue && (
+                <>
+                    &nbsp;
+                    <span className={`hui-text-h1 text-${isUrgent ? 'text-critical' : 'text-primary'}`}>
+                        {altDurationValue}
+                    </span>
+                </>
+            )}
+            <H3
+                className="ml-2"
+                color="secondary"
+            >
+                {label}
+            </H3>
+        </div>
+    );
+};

package/src/Countdown/Countdown.types.ts

@@ -0,0 +1,4 @@
+export type CountdownFlashpoint = {
+    duration: 'd' | 'h' | 'm' | 's';
+    value: number;
+};