@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/SplitButton/SplitButton.tsx

@@ -0,0 +1,298 @@
+import { cn } from '@evolve.ui/theme-system';
+import {
+    autoUpdate,
+    flip,
+    FloatingFocusManager,
+    FloatingList,
+    FloatingPortal,
+    FloatingTree,
+    offset,
+    Placement,
+    shift,
+    size,
+    useClick,
+    useDismiss,
+    useFloating,
+    useFloatingNodeId,
+    useFloatingTree,
+    useInteractions,
+    useListNavigation,
+    useRole,
+    useTypeahead,
+} from '@floating-ui/react';
+import { ReactNode, useEffect, useRef, useState } from 'react';
+
+import { Button } from '../Button/Button';
+import { MenuContext } from '../Menu/context/menuContext';
+import { SplitButtonTrigger } from './SplitButtonTrigger';
+
+/** SSR guard — prevents hydration mismatch on FloatingPortal (same pattern as Menu.tsx) */
+const useHasMounted = () => {
+    const [hasMounted, setHasMounted] = useState(false);
+    useEffect(() => {
+        setHasMounted(true);
+    }, []);
+    return hasMounted;
+};
+
+type Props = {
+    /**
+     * Accessible label for the split button group wrapper.
+     * Defaults to the string value of `label` when `label` is a string.
+     */
+    'aria-label'?: string;
+    /**
+     * `MenuItem` components to render inside the dropdown.
+     *
+     * Usage:
+     * ```tsx
+     * <SplitButton label="Export CSV" onDefaultAction={handleExport}>
+     *   <MenuItem primaryLabel="Export PDF" onClick={handlePdf} />
+     *   <MenuItem primaryLabel="Export Excel" onClick={handleExcel} />
+     * </SplitButton>
+     * ```
+     */
+    children: ReactNode;
+    /** Additional CSS class applied to the wrapper element */
+    className?: string;
+    /** Test id applied to the wrapper element for consumer test targeting */
+    'data-testid'?: string;
+    /** Disables both the default action button and the menu trigger */
+    disabled?: boolean;
+    /** Label for the default action button */
+    label: ReactNode;
+    /**
+     * Shows a loading spinner on the default action button and disables the
+     * dropdown trigger to prevent new selections while an action is in-flight.
+     *
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Preferred placement of the dropdown menu. Flip middleware will
+     * automatically move it to the opposite side if there is insufficient
+     * viewport space.
+     *
+     * @default 'bottom-start'
+     */
+    menuPlacement?: Placement;
+    /**
+     * Accessible label for the menu trigger (caret) button.
+     * Defaults to `"See more {label} actions"` when `label` is a string.
+     */
+    menuTriggerAriaLabel?: string;
+    /** Callback fired when the default action button is clicked */
+    onDefaultAction: () => void;
+    /**
+     * Button size.
+     *
+     * @default 'md'
+     */
+    size?: 'md' | 'sm';
+    /**
+     * Visual variant — `'filled'` (primary) or `'outlined'` (secondary).
+     *
+     * @default 'filled'
+     */
+    variant?: 'filled' | 'outlined';
+};
+
+const SplitButtonContent = ({
+    'aria-label': ariaLabel,
+    children,
+    className,
+    'data-testid': dataTestId,
+    disabled = false,
+    label,
+    loading = false,
+    menuPlacement = 'bottom-start',
+    menuTriggerAriaLabel,
+    onDefaultAction,
+    size: sizeProp = 'md',
+    variant = 'filled',
+}: Props) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState<number | null>(null);
+    const elementsRef = useRef<Array<HTMLSpanElement | null>>([]);
+    const labelsRef = useRef<Array<string | null>>([]);
+    const hasMounted = useHasMounted();
+
+    const tree = useFloatingTree();
+    const nodeId = useFloatingNodeId();
+
+    const { context, floatingStyles, refs } = useFloating<HTMLDivElement>({
+        middleware: [
+            offset(8),
+            flip(),
+            shift({ padding: 2 }),
+            // Match the menu width to the full button width (action + trigger combined)
+            size({
+                apply({ elements, rects }) {
+                    elements.floating.style.minWidth = `${rects.reference.width}px`;
+                },
+            }),
+        ],
+        nodeId,
+        onOpenChange: setIsOpen,
+        open: isOpen,
+        placement: menuPlacement,
+        whileElementsMounted: autoUpdate,
+    });
+
+    const click = useClick(context, { event: 'click' });
+    const dismiss = useDismiss(context, { bubbles: true });
+    const role = useRole(context, { role: 'menu' });
+    const listNavigation = useListNavigation(context, {
+        activeIndex,
+        focusItemOnOpen: false,
+        listRef: elementsRef,
+        onNavigate: setActiveIndex,
+    });
+
+    const typeahead = useTypeahead(context, {
+        activeIndex,
+        listRef: labelsRef,
+        onMatch: isOpen ? setActiveIndex : undefined,
+    });
+
+    const { getFloatingProps, getItemProps, getReferenceProps } = useInteractions([
+        click,
+        dismiss,
+        role,
+        listNavigation,
+        typeahead,
+    ]);
+
+    // Close the dropdown when any MenuItem fires its click tree event.
+    // MenuItem calls tree.events.emit('click') on selection, so we listen here
+    // rather than relying on DOM event bubbling (which MenuItem stops).
+    useEffect(() => {
+        if (!tree) {
+            return;
+        }
+
+        function handleTreeClick() {
+            setIsOpen(false);
+        }
+
+        tree.events.on('click', handleTreeClick);
+        return () => {
+            tree.events.off('click', handleTreeClick);
+        };
+    }, [tree]);
+
+    const resolvedMenuTriggerAriaLabel =
+        menuTriggerAriaLabel ?? (typeof label === 'string' ? `See more ${label} actions` : 'See more actions');
+
+    return (
+        // The wrapper div is the floating-ui reference so placement and min-width
+        // are relative to the full combined button, not just the caret trigger.
+        <div
+            aria-label={ariaLabel ?? (typeof label === 'string' ? label : undefined)}
+            className={cn('relative inline-flex items-stretch', className)}
+            data-hui-id="SplitButton"
+            data-testid={dataTestId}
+            ref={refs.setReference}
+            role="group"
+        >
+            <Button
+                className={cn(
+                    '!rounded-r-none',
+                    loading && {
+                        '!outline-border-disabled': variant === 'outlined',
+                    }
+                )}
+                disabled={disabled}
+                loading={loading}
+                onClick={onDefaultAction}
+                size={sizeProp}
+                style="primary"
+                variant={variant}
+            >
+                {label}
+            </Button>
+
+            {variant === 'filled' && (
+                <div
+                    aria-hidden
+                    className="w-px shrink-0 self-stretch bg-text-inverse"
+                />
+            )}
+
+            <SplitButtonTrigger
+                aria-label={resolvedMenuTriggerAriaLabel}
+                className={cn(
+                    // When loading (not genuinely disabled), keep active visual styles
+                    // but let disabled:cursor-not-allowed through for the not-allowed cursor.
+                    loading && !disabled && variant === 'filled' && 'disabled:!bg-primary-500',
+                    loading &&
+                        !disabled &&
+                        variant === 'outlined' &&
+                        'disabled:!bg-background-primary disabled:!outline-primary-500'
+                )}
+                disabled={disabled || loading}
+                isOpen={isOpen}
+                size={sizeProp}
+                variant={variant}
+                {...getReferenceProps()}
+            />
+
+            <MenuContext.Provider
+                value={{
+                    activeIndex,
+                    getItemProps,
+                    isOpen,
+                    numberOfColumns: 1,
+                    setActiveIndex,
+                }}
+            >
+                <FloatingList
+                    elementsRef={elementsRef}
+                    labelsRef={labelsRef}
+                >
+                    {isOpen && hasMounted && Boolean(refs.domReference) && (
+                        <FloatingPortal root={refs.domReference}>
+                            <FloatingFocusManager
+                                context={context}
+                                initialFocus={-1}
+                                modal={false}
+                                returnFocus
+                            >
+                                <div
+                                    className="Menu z-50 cursor-default whitespace-nowrap rounded-container bg-background-primary py-xs text-text-primary shadow-03 outline-0"
+                                    data-testid="split-button-menu"
+                                    ref={refs.setFloating}
+                                    style={floatingStyles}
+                                    {...getFloatingProps()}
+                                >
+                                    {children}
+                                </div>
+                            </FloatingFocusManager>
+                        </FloatingPortal>
+                    )}
+                </FloatingList>
+            </MenuContext.Provider>
+        </div>
+    );
+};
+
+/**
+ * A split button pairs a primary default action with a dropdown menu of
+ * related secondary actions. The left button triggers the action immediately;
+ * the right caret button opens the dropdown.
+ *
+ * Use `MenuItem` children to populate the dropdown:
+ * ```tsx
+ * <SplitButton label="Export CSV" onDefaultAction={handleExport}>
+ *   <MenuItem primaryLabel="Export PDF" onClick={handlePdf} />
+ *   <MenuItem primaryLabel="Export Excel" onClick={handleExcel} />
+ * </SplitButton>
+ * ```
+ */
+export const SplitButton = (props: Props) => (
+    <FloatingTree>
+        <SplitButtonContent {...props} />
+    </FloatingTree>
+);
+
+SplitButton.displayName = 'SplitButton';

package/src/SplitButton/SplitButtonTrigger.tsx

@@ -0,0 +1,55 @@
+import { cn } from '@evolve.ui/theme-system';
+import { forwardRef, HTMLProps } from 'react';
+
+import { filledPrimaryClasses, outlinedPrimaryClasses } from '../Button/buttonColorClasses';
+import { CaretDown } from '../Icons/generatedIcons/CaretDown';
+
+type Props = {
+    /** Whether the menu is currently open — applies pressed visual state to the trigger */
+    isOpen?: boolean;
+    /** Button size, should match the adjacent default action button */
+    size?: 'md' | 'sm';
+    /** Visual variant */
+    variant?: 'filled' | 'outlined';
+} & Omit<HTMLProps<HTMLButtonElement>, 'size' | 'type'>;
+
+/**
+ * The caret trigger button used inside `SplitButton`. Renders a square button
+ * with a `CaretDown` icon, styled to join seamlessly with the default action button.
+ *
+ * Not intended for standalone use — use `SplitButton` instead.
+ */
+export const SplitButtonTrigger = forwardRef<HTMLButtonElement, Props>(
+    ({ className, disabled = false, isOpen = false, size = 'md', variant = 'filled', ...rest }, ref) => {
+        const isFilled = variant === 'filled';
+
+        return (
+            <button
+                className={cn(
+                    'hui-focus-visible-outline relative flex items-center justify-center rounded-l-none rounded-r-button outline outline-1 -outline-offset-1 transition-colors',
+                    isFilled ? filledPrimaryClasses : cn(outlinedPrimaryClasses, 'ml-[-1px]'),
+                    {
+                        'size-[34px]': size === 'sm',
+                        'size-[42px]': size === 'md',
+                        // Force the pressed/active visual while the menu is open
+                        '!bg-primary-200 !text-primary-900': isOpen && !isFilled,
+                        '!bg-primary-900': isOpen && isFilled,
+                    },
+                    className
+                )}
+                data-hui-id="SplitButtonTrigger"
+                disabled={disabled}
+                ref={ref}
+                type="button"
+                {...rest}
+            >
+                <CaretDown
+                    size={size === 'md' ? 'sm' : 'xs'}
+                    style="bold"
+                />
+            </button>
+        );
+    }
+);
+
+SplitButtonTrigger.displayName = 'SplitButtonTrigger';

package/src/StarRating/StarRating.tsx

@@ -0,0 +1,165 @@
+import { cn } from '@evolve.ui/theme-system';
+import { MouseEvent, ReactNode } from 'react';
+
+import { iconSizesToPixels } from '../Icons/IconBase';
+import { LabelStrong } from '../Typography/Text/Text';
+import { StarComponent } from './components/StarComponent/StarComponent';
+
+type StarRatingProps = {
+    'aria-label'?: string;
+    /**
+     * How to pass the average rating.
+     * Value should be between 0 and maxAmountOfStars
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} />
+     * ```
+     */
+    averageRating: number;
+    className?: string;
+    /**
+     * Optional value to define the compact mode.
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} compact />
+     * ```
+     */
+    compact?: boolean;
+    /**
+     * Optional value to define the emphasis of the star rating.
+     * Default value is subtle
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} emphasis='bold' />
+     * ```
+     */
+    emphasis?: 'subtle' | 'bold';
+    /**
+     * Optional value to define the maximum number of stars to display.
+     * Default value is 5
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} maxAmountOfStars={10} />
+     * ```
+     */
+    maxAmountOfStars?: number;
+    /**
+     * Optional value to define the onClick event handler.
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} onClick={() => console.log('clicked')} />
+     * ```
+     */
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Optional value to define the size of the icons.
+     * Default value is sm
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} size={'xs'} />
+     * ```
+     */
+    size?: Extract<keyof typeof iconSizesToPixels, 'sm' | 'xs'>;
+    /**
+     * Optional value of trailing text.
+     *
+     * Usage:
+     * ```tsx
+     * <StarRating averageRating={4.5} trailingText="100 Reviews" />
+     * ```
+     */
+    trailingText?: string;
+};
+
+export const StarRating = ({
+    averageRating,
+    className,
+    compact = false,
+    emphasis = 'subtle',
+    maxAmountOfStars = 5,
+    onClick,
+    size = 'sm',
+    trailingText,
+    ...rest
+}: StarRatingProps) => {
+    const fullStars = Math.floor(averageRating);
+    const partialStarPercentage = (averageRating - fullStars) * 100;
+
+    // If a click action is provided, wrap the component in a button
+    const ParentWrapper = ({ children }: { children: ReactNode }) => {
+        return onClick ? (
+            <button
+                aria-label={rest['aria-label'] ?? 'Star Rating'}
+                className={cn('group hui-focus-visible-outline flex items-center', className)}
+                data-hui-id="StarRating"
+                onClick={onClick}
+                title={`${Math.floor(averageRating * 10) / 10} stars`}
+            >
+                {children}
+            </button>
+        ) : (
+            <div
+                aria-label={rest['aria-label'] ?? 'Star Rating'}
+                className={cn('flex items-center', className)}
+                data-hui-id="StarRating"
+                title={`${Math.floor(averageRating * 10) / 10} stars`}
+            >
+                {children}
+            </div>
+        );
+    };
+
+    return (
+        <ParentWrapper>
+            {/* If compact, render a label and a star */}
+            {compact ? (
+                <>
+                    <LabelStrong
+                        className={cn('mr-[2px]', {
+                            'group-hover:cursor-pointer': onClick !== undefined,
+                        })}
+                        color="secondary"
+                    >
+                        {Math.floor(averageRating * 10) / 10}
+                    </LabelStrong>
+                    <StarComponent
+                        emphasis={emphasis}
+                        filledPercentage={100}
+                        index={0}
+                        size="xs"
+                    />
+                </>
+            ) : (
+                [...Array(maxAmountOfStars)].map((_, index) => (
+                    <StarComponent
+                        emphasis={emphasis}
+                        filledPercentage={index < fullStars ? 100 : index === fullStars ? partialStarPercentage : 0}
+                        index={index}
+                        key={index}
+                        size={size}
+                    />
+                ))
+            )}
+
+            {trailingText && (
+                <span
+                    className={cn('text-text-secondary', {
+                        'group-hover:text-link-hover group-hover:underline': onClick !== undefined,
+                        'hui-text-body-secondary': size === 'sm' || compact,
+                        'hui-text-caption': size === 'xs' && !compact,
+                        'ml-2xs': !compact,
+                        'ml-[2px]': compact,
+                    })}
+                >
+                    {!compact ? trailingText : `(${trailingText})`}
+                </span>
+            )}
+        </ParentWrapper>
+    );
+};

package/src/StarRating/components/StarComponent/StarComponent.tsx

@@ -0,0 +1,44 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { Star } from '../../../Icons';
+import { iconSizesToPixels } from '../../../Icons/IconBase';
+
+type StarComponentProps = {
+    emphasis: 'subtle' | 'bold';
+    filledPercentage: number;
+    index: number;
+    size: Extract<keyof typeof iconSizesToPixels, 'sm' | 'xs'>;
+};
+
+export const StarComponent = ({ emphasis, filledPercentage, index, size }: StarComponentProps) => {
+    return (
+        <div
+            className={cn('relative inline-block', {
+                'h-[14px] w-[14px]': size === 'xs',
+                'h-[20px] w-[20px]': size === 'sm',
+            })}
+            data-hui-id="StarRating"
+        >
+            <Star
+                className={cn('absolute left-0 top-0 z-[1]', {
+                    'text-icon-primary': emphasis === 'subtle',
+                    'text-warning-700': emphasis === 'bold',
+                })}
+                size={size}
+                style="regular"
+            />
+            <Star
+                className={cn('absolute left-0 top-0', {
+                    'text-icon-primary': emphasis === 'subtle',
+                    'text-warning-500': emphasis === 'bold',
+                })}
+                customStyles={{
+                    clipPath: `inset(0% ${Math.round(100 - filledPercentage)}% 0% 0%)`,
+                }}
+                data-testid={`partialFilledStar-${index + 1}`}
+                size={size}
+                style="fill"
+            />
+        </div>
+    );
+};