@evolve.ui/core-components 1.0.1 → 1.2.0

package/src/EducationalPopover/EducationalPopover.tsx

@@ -0,0 +1,174 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ComponentProps, ReactElement, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { Button } from '../Button/Button';
+import { IconButton } from '../IconButton/IconButton';
+import { Close } from '../Icons';
+import { AnyIcon } from '../Icons/anyIcon';
+import { Tooltip } from '../Tooltip/Tooltip';
+import { Caption, H5 } from '../Typography/Text/Text';
+
+type Props = Omit<ComponentProps<typeof Tooltip>, 'children'> & {
+    /**
+     * The icon to show in the top-left corner.
+     * - If populated, the title is shown right below it.
+     * - If not populated, the title will show there instead.
+     * @default undefined
+     */
+    icon?: AnyIcon;
+    /**
+     * Array of ReactElements that the user will click through to become educated.
+     */
+    pages: ReactElement[];
+    /**
+     * Should the close button be shown in the top-right corner?
+     * @default false
+     */
+    showCloseButton?: boolean;
+    /**
+     * Should the step counter be shown in the bottom-left corner?
+     * If there is only a single page, it will not be shown, even if this prop is true.
+     * @default false
+     */
+    showStepCount?: boolean;
+    /**
+     * Title of the educational modal.
+     * This will be shown over the main content of every page in the education flow.
+     * - If `icon` is populated, the title is shown right below it.
+     * - If `icon` is not populated, the title will show across from the close button instead.
+     */
+    title?: string;
+};
+
+export const EducationalPopover = ({
+    icon: Icon,
+    isOpen: isOpenProp = true,
+    pages,
+    showCloseButton = false,
+    showStepCount = false,
+    title,
+    ...tooltipProps
+}: Props) => {
+    const [isOpen, setIsOpen] = useState(isOpenProp);
+
+    const [currentPage, setCurrentPage] = useState(0);
+    const pageCount = pages.length;
+    const hasMultiplePages = pageCount > 1;
+    const isOnLastPage = currentPage + 1 === pageCount;
+
+    const showTopRow = Icon || title || showCloseButton;
+    const showLowerTitleRow = Icon && title;
+    const showBottomRow = hasMultiplePages;
+
+    const pageContent = useMemo(() => pages[currentPage], [currentPage, pages]);
+
+    const onClose = useCallback(() => {
+        setIsOpen(false);
+    }, []);
+
+    const onClickNextButton: ComponentProps<typeof Button>['onClick'] = useCallback(() => {
+        // User pressed "Got It" and will close popover
+        if (isOnLastPage) {
+            onClose();
+        }
+        // User pressed "Next" and will go to next page
+        else {
+            setCurrentPage((currentPage) => currentPage + 1);
+        }
+    }, [isOnLastPage, onClose]);
+
+    useEffect(() => {
+        setCurrentPage(0);
+    }, [isOpen, pages]);
+
+    useEffect(() => {
+        setIsOpen(isOpenProp);
+    }, [isOpenProp]);
+
+    if (pages.length === 0) {
+        return null;
+    }
+
+    return (
+        <Tooltip
+            className="!rounded-none"
+            isOpen={isOpen}
+            style={{ minWidth: '314px' }}
+            {...tooltipProps}
+            clickable
+            globalCloseEvents={{
+                clickOutsideAnchor: true,
+                escape: true,
+            }}
+            setIsOpen={setIsOpen}
+        >
+            <section className="py-xs">
+                {/* icon / close button */}
+                {showTopRow && (
+                    <div className="mb-xs flex items-center justify-between">
+                        {/* if icon exists, place it across from close button */}
+                        {Icon && <Icon color={tooltipProps.isInverse ? 'inverse' : 'primary'} />}
+                        {/* if icon does not exist, title is across from close button*/}
+                        {!Icon && title && <H5 color={tooltipProps.isInverse ? 'inverse' : 'primary'}>{title}</H5>}
+
+                        {showCloseButton && (
+                            <IconButton
+                                icon={Close}
+                                onClick={onClose}
+                                style={tooltipProps.isInverse ? 'inverse' : 'neutral'}
+                            />
+                        )}
+                    </div>
+                )}
+                {/* title is under icon if icon exists */}
+                {showLowerTitleRow && (
+                    <H5
+                        className="mb-xs"
+                        color={tooltipProps.isInverse ? 'inverse' : 'primary'}
+                    >
+                        {title}
+                    </H5>
+                )}
+                {/* main educational info */}
+                {pageContent}
+                {/* bottom content */}
+                {showBottomRow && (
+                    <div
+                        className={cn('mt-sm flex items-center', {
+                            'justify-between': showStepCount || !isOnLastPage,
+                            'justify-end': !(showStepCount || !isOnLastPage),
+                        })}
+                    >
+                        {showStepCount && (
+                            <Caption
+                                className="items-start"
+                                color={tooltipProps.isInverse ? 'inverse' : 'primary'}
+                            >
+                                {currentPage + 1} of {pageCount}
+                            </Caption>
+                        )}
+                        <div className="flex items-end gap-sm">
+                            {!isOnLastPage && (
+                                <Button
+                                    onClick={onClose}
+                                    size="sm"
+                                    style={tooltipProps.isInverse ? 'inverse' : 'primary'}
+                                    variant="transparent"
+                                >
+                                    Skip
+                                </Button>
+                            )}
+                            <Button
+                                onClick={onClickNextButton}
+                                size="sm"
+                                style={tooltipProps.isInverse ? 'inverse' : 'primary'}
+                            >
+                                {isOnLastPage ? 'Got It' : 'Next'}
+                            </Button>
+                        </div>
+                    </div>
+                )}
+            </section>
+        </Tooltip>
+    );
+};

package/src/FavoriteButton/FavoriteButton.tsx

@@ -0,0 +1,64 @@
+import { forwardRef } from 'react';
+
+import { Tooltip } from '../Tooltip/Tooltip';
+import { IconOnlyFavoriteButton } from './components/IconOnlyFavoriteButton/IconOnlyFavoriteButton';
+import { LabeledAnimatedFavoriteButton } from './components/LabeledAnimatedFavoriteButton/LabeledAnimatedFavoriteButton';
+import { LabeledFavoriteButton } from './components/LabeledFavoriteButton/LabeledFavoriteButton';
+import { FavoriteButtonProps } from './types/favoriteButton';
+
+/**
+ * A button that allows users to mark an item as a favorite.
+ * The button displays a heart icon that changes appearance when favorited.
+ *
+ * Be aware that if you're using the tooltip option, make sure to use a unique id
+ * and set the `anchorSelect` prop on the tooltip to the id of the button.
+ *
+ * Available in four variants:
+ * - `circle`: Shows only the heart icon in a circular button (default)
+ * - `square`: Shows only the heart icon in a square button
+ * - `labeled`: Shows a button with text and the heart icon
+ * - `labeled-animated`: Shows a labeled button with animation-ready wrappers
+ */
+export const FavoriteButton = forwardRef<HTMLButtonElement, FavoriteButtonProps>((props, ref) => {
+    const { isActivating, isWiggling, tooltipProps, variant = 'circle', ...restProps } = props;
+    const { enabled = false, ...tooltipRestProps } = tooltipProps ?? {};
+
+    // Use a mapping object to determine which component to render
+    const variantComponents = {
+        circle: (
+            <IconOnlyFavoriteButton
+                ref={ref}
+                shape="circle"
+                {...restProps}
+            />
+        ),
+        labeled: (
+            <LabeledFavoriteButton
+                ref={ref}
+                {...restProps}
+            />
+        ),
+        'labeled-animated': (
+            <LabeledAnimatedFavoriteButton
+                ref={ref}
+                isActivating={isActivating}
+                isWiggling={isWiggling}
+                {...restProps}
+            />
+        ),
+        square: (
+            <IconOnlyFavoriteButton
+                ref={ref}
+                shape="square"
+                {...restProps}
+            />
+        ),
+    };
+
+    return (
+        <>
+            {enabled && <Tooltip {...tooltipRestProps} />}
+            {variantComponents[variant]}
+        </>
+    );
+});

package/src/FavoriteButton/components/IconOnlyFavoriteButton/IconOnlyFavoriteButton.tsx

@@ -0,0 +1,83 @@
+import { cn } from '@evolve.ui/theme-system';
+import { forwardRef } from 'react';
+
+import { HeartStraight } from '../../../Icons';
+import { useFavoriteButtonState } from '../../hooks/useFavoriteButtonState';
+import { IconOnlyFavoriteButtonProps } from '../../types/favoriteButton';
+
+/**
+ * Icon-only variant of the FavoriteButton component
+ * Displays only a heart icon in either a circle or square shape
+ */
+export const IconOnlyFavoriteButton = forwardRef<HTMLButtonElement, IconOnlyFavoriteButtonProps>(
+    (
+        {
+            'aria-label': ariaLabel = 'Favorite Toggle',
+            className,
+            disabled,
+            favorited,
+            onClick,
+            shape,
+            type,
+            ...restProps
+        },
+        ref
+    ) => {
+        const { handleMouseDown, handleMouseLeave, handleMouseUp, isActive } = useFavoriteButtonState();
+
+        return (
+            <button
+                aria-label={ariaLabel}
+                aria-pressed={Boolean(favorited)}
+                className={cn(
+                    // Base styles
+                    'group flex h-[30px] w-[30px] cursor-pointer items-center justify-center border border-solid',
+                    // Shape styles
+                    {
+                        'rounded-container': shape === 'square',
+                        'rounded-full': shape === 'circle',
+                    },
+                    // Default state
+                    'bg-background-primary text-surface-500',
+                    // Selected state
+                    {
+                        'bg-background-primary text-critical-500': favorited,
+                    },
+                    // Focus state
+                    // Atomic: the bare-focus outline suppression had to go in the same edit as the de-prefix.
+                    // Prefixed,
+                    // the ring was 0,3,0 and beat it; bare it is 0,2,0 and would lose (DS-98 Phase 0).
+                    'hui-focus-visible-outline focus-visible:outline-offset-1',
+                    // Active state - immediately show critical color when clicked
+                    'active:text-border-critical-400 active:bg-critical-50',
+                    // Hover state
+                    'hover:bg-critical-50 hover:text-critical-400',
+                    // Disabled state
+                    'disabled:cursor-not-allowed disabled:bg-background-primary disabled:text-border-disabled',
+                    className
+                )}
+                data-hui-id="FavoriteButton"
+                disabled={disabled}
+                onClick={onClick}
+                onMouseDown={handleMouseDown}
+                onMouseLeave={handleMouseLeave}
+                onMouseUp={handleMouseUp}
+                ref={ref}
+                type={type as 'button' | 'submit' | 'reset' | undefined}
+                {...restProps}
+            >
+                <HeartStraight
+                    className={cn(
+                        'mt-[1px] bg-transparent text-current transition-transform duration-200 ease-in-out',
+                        {
+                            'group-hover:scale-[1.125]': !disabled,
+                        }
+                    )}
+                    color="inherit"
+                    size="sm"
+                    style={favorited || isActive ? 'fill' : 'regular'}
+                />
+            </button>
+        );
+    }
+);

package/src/FavoriteButton/components/LabeledAnimatedFavoriteButton/LabeledAnimatedFavoriteButton.tsx

@@ -0,0 +1,186 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ButtonHTMLAttributes, CSSProperties, forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+
+import { outlinedCriticalClasses, outlinedNeutralClasses } from '../../../Button/buttonColorClasses';
+import { HeartStraight } from '../../../Icons';
+import { SaveConfetti, type SaveConfettiHandle } from '../../../SaveConfetti/SaveConfetti';
+import { useFavoriteButtonState } from '../../hooks/useFavoriteButtonState';
+
+/**
+ * Labeled-animated variant of the FavoriteButton component.
+ *
+ * Visually identical to the `labeled` variant but exposes `isWiggling` and
+ * `isActivating` props that trigger the enhanced save-button nudge animations:
+ *
+ * - `isWiggling`: side-to-side wiggle (button), 3D twirl + bloom (heart icon),
+ *   color flash (critical fill pulse on heart when not favorited), and shimmer (label text).
+ *   During nudge the heart uses `fill` weight with critical color; at rest unfavorited uses `bold`.
+ *   Apply for ~650ms, then reset to false to re-arm.
+ *
+ * - `isActivating`: pulse (button) and heart pop (icon). Apply for ~500ms.
+ *
+ * Animation CSS is driven by Tailwind `animate-*` utilities from the theme plugin
+ * (`theme.extend.animation`) — no runtime style injection. The shimmer uses the
+ * `.hui-fb-shimmer` component class from the plugin for its multi-property CSS.
+ * The heart-color flash uses `.hui-fb-color-flash` to animate fill on the nested
+ * SVG path via a descendant selector. Icon weight: `bold` when unfavorited at rest,
+ * `fill` during nudge, favorited, or active press — matching the static `labeled` variant at rest.
+ *
+ * Reduced motion is gated once at the registry level
+ * (`theme-system/src/tailwind/reducedMotion.ts`), so these call sites deliberately carry no
+ * `motion-reduce:` variants — adding them back would reintroduce a second mechanism. The
+ * shimmer is the one exception: `.hui-fb-shimmer` also drops its gradient under reduce, because
+ * the label is painted *by* that gradient (`-webkit-text-fill-color: transparent`) and would
+ * otherwise be illegible.
+ */
+
+type Props = {
+    /** Accessible label for screen readers. @default 'Favorite Toggle' */
+    'aria-label'?: string;
+    /** Whether the item is currently favorited. */
+    favorited?: boolean;
+    /** Label text shown when favorited. @default 'Saved' */
+    favoritedLabel?: string;
+    /**
+     * When true, fires the save-click animation (button pulse + heart pop) and
+     * a mini confetti burst from the button center.
+     * Reset to false after ~500ms to re-arm.
+     */
+    isActivating?: boolean;
+    /**
+     * When true, fires the nudge animation (wiggle + twirl + shimmer + color flash).
+     * Reset to false after ~650ms to re-arm.
+     */
+    isWiggling?: boolean;
+    /** Label text shown when not favorited. @default 'Save' */
+    label?: string;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'style'>;
+
+type AnimationPaletteCSSVar =
+    | '--hui-save-color-critical-500'
+    | '--hui-save-color-critical-300'
+    | '--hui-save-color-critical-200'
+    | '--hui-save-color-tertiary-400'
+    | '--hui-save-color-tertiary-200';
+
+const BUTTON_INLINE_STYLES: CSSProperties & Record<AnimationPaletteCSSVar, string> = {
+    fontSize: 'var(--font-size-button-200)',
+    fontWeight: 'var(--font-weight-button)',
+    textTransform: 'var(--text-transform-button)' as CSSProperties['textTransform'],
+    // Expose canonical animation palette tokens for downstream orchestration.
+    '--hui-save-color-critical-500': 'var(--color-critical-500)',
+    '--hui-save-color-critical-300': 'var(--color-critical-300)',
+    '--hui-save-color-critical-200': 'var(--color-critical-200)',
+    '--hui-save-color-tertiary-400': 'var(--color-tertiary-400)',
+    '--hui-save-color-tertiary-200': 'var(--color-tertiary-200)',
+};
+
+export const LabeledAnimatedFavoriteButton = forwardRef<HTMLButtonElement, Props>(
+    (
+        {
+            'aria-label': ariaLabel = 'Favorite Toggle',
+            className,
+            disabled,
+            favorited,
+            favoritedLabel = 'Saved',
+            isActivating,
+            isWiggling,
+            label = 'Save',
+            onClick,
+            ...restProps
+        },
+        ref
+    ) => {
+        const { handleMouseDown, handleMouseLeave, handleMouseUp, isActive } = useFavoriteButtonState();
+
+        const internalButtonRef = useRef<HTMLButtonElement>(null);
+        const confettiRef = useRef<SaveConfettiHandle>(null);
+
+        // Preserve consumer-facing ref contract while keeping internal button access for confetti
+        useImperativeHandle(ref, () => internalButtonRef.current!);
+
+        // Fire confetti burst when the save-click animation triggers
+        useEffect(() => {
+            if (!isActivating || !internalButtonRef.current) {
+                return;
+            }
+            confettiRef.current?.fire(internalButtonRef.current);
+        }, [isActivating]);
+
+        return (
+            <>
+                <button
+                    aria-busy={false}
+                    aria-label={ariaLabel}
+                    aria-live="polite"
+                    aria-pressed={favorited ?? false}
+                    className={cn(
+                        // Base — exact match to Button's base class string
+                        'hui-focus-visible-outline relative flex max-w-full items-center justify-center whitespace-nowrap rounded-button text-center font-primary tracking-[var(--letter-spacing-button)] outline outline-1 -outline-offset-1 transition-colors disabled:text-text-disabled',
+                        // Color classes — same conditional used by LabeledFavoriteButton
+                        favorited ? outlinedCriticalClasses : outlinedNeutralClasses,
+                        // sm size
+                        'gap-[4px] px-sm py-[13px] leading-[8px]',
+                        // Height override (matches LabeledFavoriteButton)
+                        'h-[34px]',
+                        // Favorited state border
+                        { 'border-critical-500 text-critical-500': favorited },
+                        // Hover/active overrides — same className passed by LabeledFavoriteButton to Button
+                        'hover:border-critical-700 hover:bg-critical-50 hover:text-critical-700',
+                        'active:border-critical-900 active:bg-critical-100 active:text-critical-900',
+                        // Nudge animation — wiggle on button root + color flash on nested SVG path
+                        isWiggling && 'animate-saveButtonWiggle',
+                        isWiggling && !favorited && 'hui-fb-color-flash',
+                        // Save-click animation — pulse on button root
+                        isActivating && 'animate-saveButtonPulse',
+                        className
+                    )}
+                    data-hui-id="FavoriteButton"
+                    disabled={disabled}
+                    onClick={onClick}
+                    onMouseDown={handleMouseDown}
+                    onMouseLeave={handleMouseLeave}
+                    onMouseUp={handleMouseUp}
+                    ref={internalButtonRef}
+                    style={BUTTON_INLINE_STYLES}
+                    {...restProps}
+                >
+                    {/*
+                     * Perspective wrapper — 3D twirl animation targets this element.
+                     * Width/height matches Button's internal iconLeft container (14px for xs icon).
+                     */}
+                    <span
+                        className={cn(
+                            'hui-fb-icon-frame relative flex items-center justify-center',
+                            // Critical color during nudge so fill weight reads red immediately (not surface-500 grey)
+                            isWiggling && !favorited && 'text-critical-500',
+                            // Nudge animation — 3D twirl + bloom on icon frame
+                            isWiggling && 'animate-saveHeartTwirlBloom'
+                        )}
+                        style={{ height: '14px', perspective: '200px', width: '14px' }}
+                    >
+                        <HeartStraight
+                            className={cn(
+                                '[transform-style:preserve-3d]',
+                                // Save-click animation — heart pop on SVG element
+                                isActivating && 'animate-saveHeartPop'
+                            )}
+                            color="inherit"
+                            size="xs"
+                            style={favorited || isActive || isWiggling ? 'fill' : 'bold'}
+                        />
+                    </span>
+                    {/* Shimmer wrapper — .hui-fb-shimmer bundles background-clip + gradient + animation */}
+                    <span
+                        className={cn('hui-fb-animated-label', isWiggling && 'hui-fb-shimmer animate-saveLabelShimmer')}
+                    >
+                        {favorited ? favoritedLabel : label}
+                    </span>
+                </button>
+                <SaveConfetti ref={confettiRef} />
+            </>
+        );
+    }
+);
+
+LabeledAnimatedFavoriteButton.displayName = 'LabeledAnimatedFavoriteButton';

package/src/FavoriteButton/components/LabeledFavoriteButton/LabeledFavoriteButton.tsx

@@ -0,0 +1,71 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ButtonHTMLAttributes, forwardRef } from 'react';
+
+import { Button } from '../../../Button/Button';
+import { useFavoriteButtonState } from '../../hooks/useFavoriteButtonState';
+import { SmallHeartStraightIcon } from '../SmallHeartStraightIcon/SmallHeartStraightIcon';
+
+/**
+ * Labeled variant of the FavoriteButton component
+ * Displays a button with text and a heart icon
+ */
+
+type Props = {
+    'aria-label'?: string;
+    favorited?: boolean;
+    favoritedLabel?: string;
+    label?: string;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'style' | 'children'>;
+
+export const LabeledFavoriteButton = forwardRef<HTMLButtonElement, Props>(
+    (
+        {
+            'aria-label': ariaLabel = 'Favorite Toggle',
+            className,
+            disabled,
+            favorited,
+            favoritedLabel = 'Saved',
+            label = 'Save',
+            onClick,
+            ...restProps
+        },
+        ref
+    ) => {
+        const { handleMouseDown, handleMouseLeave, handleMouseUp, isActive } = useFavoriteButtonState();
+
+        return (
+            <Button
+                aria-label={ariaLabel}
+                aria-pressed={favorited ? true : false}
+                className={cn(
+                    // Base styles
+                    'h-[34px] text-surface-500',
+                    // Selected state
+                    {
+                        'border-critical-500 text-critical-500': favorited,
+                    },
+                    // Hover state - same for both favorited and non-favorited
+                    'hover:border-critical-700 hover:bg-critical-50 hover:text-critical-700',
+                    // Active states - different for favorited and non-favorited
+                    'active:border-critical-900 active:bg-critical-100 active:text-critical-900',
+                    className
+                )}
+                data-hui-id="FavoriteButton"
+                disabled={disabled}
+                iconLeft={SmallHeartStraightIcon}
+                iconStyle={favorited || isActive ? 'fill' : 'bold'}
+                onClick={onClick}
+                onMouseDown={handleMouseDown}
+                onMouseLeave={handleMouseLeave}
+                onMouseUp={handleMouseUp}
+                ref={ref}
+                size="sm"
+                style={favorited ? 'critical' : 'neutral'}
+                variant="outlined"
+                {...restProps}
+            >
+                {favorited ? favoritedLabel : label}
+            </Button>
+        );
+    }
+);

package/src/FavoriteButton/components/SmallHeartStraightIcon/SmallHeartStraightIcon.tsx

@@ -0,0 +1,14 @@
+import { ComponentProps, forwardRef } from 'react';
+
+import { CaretRight, HeartStraight } from '../../../Icons';
+
+export const SmallHeartStraightIcon = forwardRef<SVGSVGElement, ComponentProps<typeof CaretRight>>((props, ref) => {
+    return (
+        <HeartStraight
+            style="bold"
+            {...props}
+            ref={ref}
+            size="xs"
+        />
+    );
+});

package/src/FavoriteButton/hooks/useFavoriteButtonState.ts

@@ -0,0 +1,30 @@
+import { useState } from 'react';
+
+/**
+ * Custom hook for managing the active state of the FavoriteButton
+ * @returns Object containing the active state and event handlers
+ */
+export const useFavoriteButtonState = () => {
+    const [isActive, setIsActive] = useState(false);
+
+    const handleMouseDown = () => {
+        setIsActive(true);
+    };
+
+    const handleMouseUp = () => {
+        setIsActive(false);
+    };
+
+    const handleMouseLeave = () => {
+        if (isActive) {
+            setIsActive(false);
+        }
+    };
+
+    return {
+        handleMouseDown,
+        handleMouseLeave,
+        handleMouseUp,
+        isActive,
+    };
+};

package/src/FavoriteButton/index.ts

@@ -0,0 +1,2 @@
+export * from './FavoriteButton';
+export * from './types/favoriteButton';