@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Menu/Menu.tsx

@@ -0,0 +1,372 @@
+import { cn } from '@evolve.ui/theme-system';
+import {
+    arrow,
+    autoUpdate,
+    flip,
+    FloatingArrow,
+    FloatingFocusManager,
+    FloatingList,
+    FloatingNode,
+    FloatingPortal,
+    FloatingTree,
+    offset,
+    Placement,
+    safePolygon,
+    shift,
+    useClick,
+    useDismiss,
+    useFloating,
+    useFloatingNodeId,
+    useFloatingParentNodeId,
+    useFloatingTree,
+    useHover,
+    useInteractions,
+    useListItem,
+    useListNavigation,
+    useMergeRefs,
+    useRole,
+    useTypeahead,
+} from '@floating-ui/react';
+import {
+    cloneElement,
+    FocusEvent,
+    forwardRef,
+    HTMLProps,
+    isValidElement,
+    MouseEvent,
+    ReactElement,
+    ReactNode,
+    useEffect,
+    useRef,
+    useState,
+} from 'react';
+
+import { MenuContext, useMenuContext } from './context/menuContext';
+
+/**
+ * Hook to detect if component has mounted (client-side only)
+ * Useful for preventing SSR hydration mismatches
+ */
+const useHasMounted = () => {
+    const [hasMounted, setHasMounted] = useState(false);
+    useEffect(() => {
+        setHasMounted(true);
+    }, []);
+    return hasMounted;
+};
+
+export type MenuProps = {
+    /** MenuItem children */
+    children?: ReactNode;
+    /** additional CSS class name for the menu container*/
+    className?: string;
+    /** when true, menu will open on first render */
+    defaultOpen?: boolean;
+    /** when true, menu borders are rounded */
+    hasRoundedBorders?: boolean;
+    /**
+     * Optional stable ID for SSR scenarios. If not provided, a unique ID will be generated.
+     * This helps prevent hydration mismatches when using SSR.
+     */
+    id?: string;
+    /** Enable menu custom content vs MenuItem children */
+    isCustomContent?: boolean;
+    /** initial menu placement */
+    menuPlacement?: Placement;
+    /** custom menu width */
+    menuSize?: 'sm' | 'md' | 'lg' | 'xl';
+    /** number of grid columns required for children */
+    numberOfColumns: 1 | 2 | 3;
+    /** callback that triggers when the menu is closed */
+    onMenuClose?: () => void;
+    /** callback that triggers when the menu is opened */
+    onMenuOpen?: () => void;
+    /** when true, menu will open on hover */
+    openOnHover?: boolean;
+    /** trigger component to open menu */
+    trigger: ReactNode;
+    /** additional CSS class name for the trigger */
+    triggerClassName?: string;
+};
+
+const MenuComponent = forwardRef<HTMLSpanElement, MenuProps & HTMLProps<HTMLSpanElement>>(
+    (
+        {
+            children,
+            className,
+            defaultOpen,
+            hasRoundedBorders = false,
+            id,
+            isCustomContent,
+            menuPlacement,
+            menuSize = 'lg',
+            numberOfColumns,
+            onMenuClose,
+            onMenuOpen,
+            openOnHover = false,
+            trigger,
+            triggerClassName,
+            ...props
+        },
+        forwardedRef
+    ) => {
+        const [isOpen, setIsOpen] = useState(defaultOpen ?? false);
+        const [activeIndex, setActiveIndex] = useState<number | null>(null);
+        const elementsRef = useRef<Array<HTMLSpanElement | null>>([]);
+        const labelsRef = useRef<Array<string | null>>([]);
+        const parent = useMenuContext();
+        const hasMounted = useHasMounted();
+
+        const tree = useFloatingTree();
+        const nodeId = useFloatingNodeId(id);
+        const parentId = useFloatingParentNodeId();
+        const item = useListItem();
+
+        const isNested = parentId !== null;
+
+        const arrowRef = useRef(null);
+
+        const { context, floatingStyles, refs } = useFloating<HTMLButtonElement>({
+            middleware: [
+                offset({ alignmentAxis: -2, mainAxis: isNested ? 2 : 8 }),
+                flip(),
+                shift({ padding: !isNested ? 2 : 0 }),
+                arrow({ element: arrowRef, padding: 5 }),
+            ],
+            nodeId,
+            onOpenChange: (open) => {
+                setIsOpen(open);
+                if (!open) {
+                    onMenuClose?.();
+                } else {
+                    onMenuOpen?.();
+                }
+            },
+            open: isOpen,
+            placement: isNested ? 'right-start' : (menuPlacement ?? 'bottom'),
+            whileElementsMounted: autoUpdate,
+        });
+        const hover = useHover(context, {
+            delay: { open: 75 },
+            enabled: isNested || openOnHover,
+            handleClose: safePolygon({ blockPointerEvents: true }),
+        });
+        const click = useClick(context, {
+            enabled: !context.dataRef.current.openEvent?.defaultPrevented && !openOnHover,
+            event: 'click',
+            ignoreMouse: isNested,
+            toggle: !isNested,
+        });
+
+        const role = useRole(context, { role: 'menu' });
+        const dismiss = useDismiss(context, { bubbles: true });
+        const listNavigation = useListNavigation(context, {
+            activeIndex,
+            focusItemOnOpen: false,
+            listRef: elementsRef,
+            nested: isNested,
+            onNavigate: setActiveIndex,
+        });
+        const typeahead = useTypeahead(context, {
+            activeIndex,
+            enabled: !isCustomContent,
+            listRef: labelsRef,
+            onMatch: isOpen ? setActiveIndex : undefined,
+        });
+
+        const { getFloatingProps, getItemProps, getReferenceProps } = useInteractions([
+            hover,
+            click,
+            role,
+            dismiss,
+            listNavigation,
+            typeahead,
+        ]);
+
+        // Event emitter allows you to communicate across tree components.
+        // This effect closes all menus when an item gets clicked anywhere
+        // in the tree.
+        useEffect(() => {
+            if (!tree) {
+                return;
+            }
+
+            function handleTreeClick() {
+                setIsOpen(false);
+                onMenuClose?.();
+            }
+
+            function onSubMenuOpen(event: { nodeId: string; parentId: string }) {
+                if (event.nodeId !== nodeId && event.parentId === parentId) {
+                    setIsOpen(false);
+                    onMenuClose?.();
+                }
+            }
+
+            tree.events.on('click', handleTreeClick);
+            tree.events.on('menuopen', onSubMenuOpen);
+
+            return () => {
+                tree.events.off('click', handleTreeClick);
+                tree.events.off('menuopen', onSubMenuOpen);
+            };
+        }, [tree, nodeId, parentId, onMenuClose]);
+
+        useEffect(() => {
+            if (isOpen && tree) {
+                tree.events.emit('menuopen', { nodeId, parentId });
+            }
+        }, [tree, isOpen, nodeId, parentId]);
+
+        // Strip the three ARIA attrs from the floating-ui reference props so the wrapper span keeps
+        // every behavior it had before (refs, click/keyboard handlers, positioning), but no longer
+        // carries ARIA that its implicit `generic` role disallows (the axe `aria-allowed-attr`
+        // violation). The three ARIA attrs are reapplied to the trigger child via `cloneElement`,
+        // landing on a node whose role natively permits them (button / link / menuitem).
+        const {
+            'aria-controls': ariaControls,
+            'aria-expanded': ariaExpanded,
+            'aria-haspopup': ariaHasPopup,
+            ...referencePropsWithoutAria
+        } = getReferenceProps(
+            parent.getItemProps({
+                ...props,
+                onClick(event: MouseEvent<HTMLButtonElement>) {
+                    event.stopPropagation();
+                    props.onClick?.(event);
+                },
+                onFocus(event: FocusEvent<HTMLButtonElement>) {
+                    props.onFocus?.(event);
+                },
+            })
+        ) as Record<string, unknown>;
+
+        const triggerIsElement = isValidElement(trigger);
+        const triggerElement = trigger as ReactElement;
+        const ariaPropsForTrigger: Record<string, unknown> = {};
+        if (ariaHasPopup !== undefined) {
+            ariaPropsForTrigger['aria-haspopup'] = ariaHasPopup;
+        }
+        if (ariaExpanded !== undefined) {
+            ariaPropsForTrigger['aria-expanded'] = ariaExpanded;
+        }
+        if (ariaControls !== undefined) {
+            ariaPropsForTrigger['aria-controls'] = ariaControls;
+        }
+
+        // For element triggers, clone the ARIA onto the child (preferred — lands on a node whose role
+        // natively permits these attrs). Note: this intentionally overrides any same-named ARIA the
+        // caller already set on the trigger; menu disclosure semantics (`aria-haspopup="menu"`) must
+        // win for the popup to be announced correctly.
+        const clonedTrigger = triggerIsElement ? cloneElement(triggerElement, ariaPropsForTrigger) : trigger;
+
+        // For non-element triggers (string / number / null), we cannot clone ARIA anywhere meaningful,
+        // so the wrapper span itself becomes the disclosure control. Adding `role="button"` +
+        // `tabIndex={0}` makes the ARIA attrs valid (no `aria-allowed-attr` violation) and preserves
+        // the screen-reader disclosure pattern. Safe because non-element triggers don't contain a
+        // nested interactive element (no `nested-interactive` violation).
+        const wrapperFallbackProps = !triggerIsElement ? { ...ariaPropsForTrigger, role: 'button' as const } : {};
+
+        return (
+            <FloatingNode id={nodeId}>
+                <span
+                    className={cn(
+                        {
+                            'w-full': isNested,
+                        },
+                        'm-0 inline-flex cursor-pointer appearance-none items-center border-none bg-none p-0 text-left no-underline outline-0 hover:no-underline',
+                        triggerClassName
+                    )}
+                    data-testid="menu-trigger-wrapper"
+                    ref={useMergeRefs([refs.setReference, item.ref, forwardedRef])}
+                    tabIndex={
+                        !triggerIsElement ? 0 : !isNested ? undefined : parent.activeIndex === item.index ? 0 : -1
+                    }
+                    {...wrapperFallbackProps}
+                    {...referencePropsWithoutAria}
+                >
+                    {clonedTrigger}
+                </span>
+                <MenuContext.Provider
+                    value={{
+                        activeIndex,
+                        getItemProps,
+                        isOpen,
+                        numberOfColumns,
+                        setActiveIndex,
+                    }}
+                >
+                    <FloatingList
+                        elementsRef={elementsRef}
+                        labelsRef={labelsRef}
+                    >
+                        {isOpen && hasMounted && Boolean(refs.domReference) && (
+                            <FloatingPortal root={refs.domReference}>
+                                <FloatingFocusManager
+                                    context={context}
+                                    initialFocus={-1}
+                                    modal={false}
+                                    returnFocus={!isNested}
+                                >
+                                    <div
+                                        className={cn(
+                                            'Menu relative z-50 w-min cursor-default bg-background-primary py-2 shadow-03 outline-0',
+                                            {
+                                                'min-w-[200px]': menuSize === 'sm',
+                                                'min-w-[250px]': menuSize === 'md',
+                                                'min-w-[300px]': menuSize === 'lg',
+                                                'min-w-[350px]': menuSize === 'xl',
+                                                'rounded-md': hasRoundedBorders,
+                                            },
+                                            className
+                                        )}
+                                        data-testid="menu-wrapper"
+                                        ref={refs.setFloating}
+                                        style={floatingStyles}
+                                        {...getFloatingProps()}
+                                    >
+                                        {!isNested && (
+                                            <FloatingArrow
+                                                className="fill-background-primary"
+                                                context={context}
+                                                ref={arrowRef}
+                                                tipRadius={hasRoundedBorders ? 2 : 0}
+                                            />
+                                        )}
+                                        {children}
+                                    </div>
+                                </FloatingFocusManager>
+                            </FloatingPortal>
+                        )}
+                    </FloatingList>
+                </MenuContext.Provider>
+            </FloatingNode>
+        );
+    }
+);
+
+MenuComponent.displayName = 'MenuComponent';
+
+export const Menu = forwardRef<HTMLSpanElement, MenuProps & HTMLProps<HTMLSpanElement>>((props, ref) => {
+    const parentId = useFloatingParentNodeId();
+
+    if (parentId === null) {
+        return (
+            <FloatingTree>
+                <MenuComponent
+                    {...props}
+                    ref={ref}
+                />
+            </FloatingTree>
+        );
+    }
+
+    return (
+        <MenuComponent
+            {...props}
+            ref={ref}
+        />
+    );
+});
+
+Menu.displayName = 'Menu';

package/src/Menu/components/MenuDivider/MenuDivider.tsx

@@ -0,0 +1,5 @@
+import { cn } from '@evolve.ui/theme-system';
+
+export const MenuDivider = ({ className }: { className?: string }) => {
+    return <div className={cn('border-t border-border-secondary', className)} />;
+};

package/src/Menu/components/MenuItem/MenuItem.tsx

@@ -0,0 +1,298 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useFloatingTree, useListItem, useMergeRefs } from '@floating-ui/react';
+import { forwardRef, HTMLAttributes, KeyboardEvent, useContext, useEffect, useMemo, useState } from 'react';
+
+import { Checkbox, RadioOption } from '../../../ChoiceListItem';
+import { AnyIcon } from '../../../Icons/anyIcon';
+import { ToggleSwitch } from '../../../ToggleSwitch/ToggleSwitch';
+import { BodyPrimary, Caption, H5 } from '../../../Typography/Text/Text';
+import { MenuContext } from '../../context/menuContext';
+
+export type MenuItemProps = {
+    /** additional CSS class name for the menu item*/
+    className?: string;
+    /** close menu after action is performed */
+    closeOnAction?: boolean;
+    /** color of menu item */
+    color?: 'disabled' | 'inherit' | 'critical' | 'info' | 'inverse' | 'success' | 'secondary' | 'primary' | 'warning';
+    /** second row description, optional */
+    description?: string;
+    /** disable menu item */
+    disabled?: boolean;
+    /** id required for all event handlers: click, checkbox,
+     * radio or toggle
+     */
+    id?: string | number;
+    /** flag if using as header, alters style and hover state */
+    isHeader?: boolean;
+    /** Icon to use on Left side of menu item, requires numberOfColumns of 3 */
+    leftIcon?: AnyIcon;
+    /** primary menu label string, required */
+    primaryLabel: string;
+    /** Icon to use on Right side of menu, requires numberOfColumns of 2 or 3  */
+    rightIcon?: AnyIcon;
+    /** secondary label to be used to right of primary label, cannot be used with rightIcon, requires numberOfColumns of 2 or 3 */
+    secondaryLabel?: string;
+} & (
+    | {
+          checked?: never;
+          id?: never;
+          onCheckboxChange?: never;
+          onClick?: never;
+          onFocus?: never;
+          onRadioChange?: never;
+          onToggleChange?: never;
+      }
+    | {
+          /** current state of control */
+          checked?: boolean;
+          /** id required for all event handlers: click, checkbox,
+           * radio or toggle
+           */
+          className?: string;
+          id?: string | number;
+          /** if present, will show checkbox on in LeftIcon space, requires numberOfColumns of 3 */
+          onCheckboxChange?: (id: string | number, checked: boolean) => void;
+          /** if present, will show checkbox on in LeftIcon space */
+          onClick?: (id: string | number) => void;
+          /** if present, trigger when MenuItem is focused */
+          onFocus?: (id: string | number) => void;
+          /** if present, will show checkbox on in LeftIcon space, requires numberOfColumns of 3 */
+          onRadioChange?: (id: string | number, checked: boolean) => void;
+          /** if present, will show checkbox on in RightIcon space, requires numberOfColumns of 2 or 3 */
+          onToggleChange?: (id: string | number, checked: boolean) => void;
+      }
+);
+
+export const MenuItem = forwardRef<HTMLDivElement, MenuItemProps & HTMLAttributes<HTMLDivElement>>(
+    (
+        {
+            checked = false,
+            className,
+            closeOnAction = false,
+            color = 'inherit',
+            description,
+            disabled,
+            id = '',
+            isHeader,
+            leftIcon: LeftIcon,
+            onCheckboxChange,
+            onClick,
+            onFocus,
+            onRadioChange,
+            onToggleChange,
+            primaryLabel,
+            rightIcon: RightIcon,
+            secondaryLabel,
+            ...rest
+        }: MenuItemProps & HTMLAttributes<HTMLDivElement>,
+        forwardedRef
+    ) => {
+        const [isChecked, setIsChecked] = useState(checked);
+        const { getItemProps, numberOfColumns } = useContext(MenuContext);
+        const { ref: itemRef } = useListItem();
+
+        const renderColor = disabled ? 'disabled' : color;
+
+        useEffect(() => {
+            setIsChecked(checked);
+        }, [checked]);
+
+        const tree = useFloatingTree();
+
+        const rightSection = useMemo(() => {
+            if (RightIcon) {
+                return (
+                    <RightIcon
+                        className="self-center justify-self-center grid-area-[right]"
+                        color={renderColor}
+                        size="sm"
+                    />
+                );
+            }
+            if (onToggleChange) {
+                // Note, event handled by component level onClick
+                return (
+                    <ToggleSwitch
+                        className="grid-area-[right]"
+                        data-testid={`menu-toggle-${id}`}
+                        dense
+                        isToggled={isChecked}
+                        tabIndex={-1}
+                    />
+                );
+            }
+            return null;
+        }, [id, RightIcon, onToggleChange, isChecked, renderColor]);
+
+        const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+            if (disabled) {
+                return;
+            }
+            if (e.code === 'Space' || e.code === 'Enter') {
+                if (onClick) {
+                    onClick(id);
+                    tree?.events.emit('click');
+                } else if (onCheckboxChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onCheckboxChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                } else if (onRadioChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onRadioChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                } else if (onToggleChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onToggleChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                }
+            }
+        };
+
+        const handleItemClick = (event: React.MouseEvent<HTMLElement>) => {
+            event.stopPropagation();
+            if (disabled) {
+                return;
+            }
+            // this is to prevent UI elements like SVGs from triggering an additional click
+            if (
+                event.target instanceof HTMLButtonElement ||
+                event.target instanceof HTMLInputElement ||
+                event.target instanceof HTMLSpanElement ||
+                event.target instanceof HTMLDivElement
+            ) {
+                if (onClick) {
+                    onClick(id);
+                    tree?.events.emit('click');
+                } else if (onCheckboxChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onCheckboxChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                } else if (onRadioChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onRadioChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                } else if (onToggleChange) {
+                    const newChecked = !isChecked;
+                    setIsChecked(newChecked);
+                    onToggleChange(id, newChecked);
+                    if (closeOnAction) {
+                        tree?.events.emit('click');
+                    }
+                }
+            }
+        };
+
+        const handleFocus = () => {
+            if (disabled) {
+                return;
+            }
+            onFocus?.(id);
+        };
+
+        return (
+            <div
+                {...rest}
+                {...getItemProps({})}
+                aria-describedby={description ? `menu-item-description-${id}` : undefined}
+                aria-disabled={disabled}
+                aria-label={primaryLabel}
+                className={cn(
+                    {
+                        'active:bg-background-hover': !isHeader,
+                        'focus:bg-background-hover': !isHeader,
+                        'hover:bg-background-hover': !isHeader,
+                    },
+                    'MenuItem relative grid w-full cursor-pointer items-center justify-start gap-x-xs border-none px-sm py-3 outline-0',
+                    className
+                )}
+                data-testid={`menu-item-${id}`}
+                onClick={handleItemClick}
+                onFocus={handleFocus}
+                onKeyDown={handleKeyDown}
+                ref={useMergeRefs([itemRef, forwardedRef])}
+                role="menuitem"
+                style={{
+                    gridTemplateAreas:
+                        numberOfColumns === 2
+                            ? "'title right' 'description right'"
+                            : numberOfColumns === 1
+                              ? "'title' 'description'"
+                              : // 3 column default
+                                "'icon title right' 'icon description right'",
+                    gridTemplateColumns:
+                        numberOfColumns === 2
+                            ? '1fr min-content'
+                            : numberOfColumns === 1
+                              ? '1fr'
+                              : // 3 column default
+                                '24px 1fr min-content',
+                    gridTemplateRows: 'min-content min-content',
+                }}
+                tabIndex={isHeader ? -1 : 0}
+            >
+                {/* LEFT */}
+                {LeftIcon && (
+                    <LeftIcon
+                        className="self-center justify-self-center grid-area-[icon]"
+                        color={renderColor}
+                        size="sm"
+                    />
+                )}
+                {onCheckboxChange && (
+                    <Checkbox.Option
+                        checked={isChecked}
+                        className="grid-area-[icon]"
+                        data-testid={`menu-checkbox-${id}`}
+                        readOnly // no onChange event is provided, handled by MenuItem propagation
+                        tabIndex={-1}
+                    />
+                )}
+                {onRadioChange && (
+                    <RadioOption
+                        checked={isChecked}
+                        className="grid-area-[icon]"
+                        data-testid={`menu-radio-${id}`}
+                        readOnly // no onChange event is provided, handled by MenuItem propagation
+                        tabIndex={-1}
+                    />
+                )}
+
+                {/* MAIN */}
+                {isHeader ? (
+                    <H5 className={cn('grid-area-[title]', `text-text-${renderColor}`)}>{primaryLabel}</H5>
+                ) : (
+                    <div className="flex items-center justify-between gap-x-xs grid-area-[title]">
+                        <BodyPrimary className={`text-text-${renderColor}`}>{primaryLabel}</BodyPrimary>
+                        {secondaryLabel && <BodyPrimary className="text-text-secondary">{secondaryLabel}</BodyPrimary>}
+                    </div>
+                )}
+                {Boolean(description?.trim()) && (
+                    <Caption className={cn('grid-area-[description]', `text-text-${renderColor}`)}>
+                        {description}
+                    </Caption>
+                )}
+
+                {/* RIGHT */}
+                {rightSection}
+            </div>
+        );
+    }
+);
+
+MenuItem.displayName = 'MenuItem';

package/src/Menu/context/menuContext.tsx

@@ -0,0 +1,20 @@
+import { createContext, Dispatch, HTMLProps, SetStateAction, useContext } from 'react';
+
+export type MenuContextType = {
+    activeIndex: number | null;
+    // eslint-disable-next-line func-call-spacing
+    getItemProps: (userProps?: HTMLProps<HTMLElement>) => Record<string, unknown>;
+    isOpen: boolean;
+    numberOfColumns: number;
+    setActiveIndex: Dispatch<SetStateAction<number | null>>;
+};
+
+export const MenuContext = createContext<MenuContextType>({
+    activeIndex: null,
+    getItemProps: () => ({}),
+    isOpen: false,
+    numberOfColumns: 3,
+    setActiveIndex: () => {},
+});
+
+export const useMenuContext = () => useContext(MenuContext);