@ringcentral/spring-ui 1.7.0

package/chunks/useMenuItemSelect.js

@@ -0,0 +1,252 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { createContext, useContext, forwardRef, useRef, useEffect, useCallback, useMemo } from 'react';
+import { useFocusVisible, useActive, useForkRef, useClasses, useId, useHover, useEventCallback } from '@ringcentral/spring-base';
+import { CheckBoldMd } from '@ringcentral/spring-icon';
+import { useThemeProps } from '@ringcentral/spring-theme';
+import { I as Icon } from './Icon.js';
+import './useNestedParentMenu.js';
+import { u as useNestedMenuItem } from './useNestedMenuItem.js';
+import { useVirtualizedItemPropsContext } from '../VirtualizedList.js';
+import { useItemNavigation } from '../ListNavigation.js';
+import { u as useMenuContext } from './Menu.js';
+
+const MenuListContext = createContext({
+    nowrap: true,
+});
+const useMenuListContext = () => useContext(MenuListContext);
+
+const MenuItemSelectContext = 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+createContext(null);
+const useMenuItemSelectContext = () => useContext(MenuItemSelectContext);
+
+const useMenuItem = (props) => {
+    const { onBlur, onFocus, onKeyDown, onKeyUp, onClick, ref, disabled, autoClose, } = props;
+    const { keyboardNavHandlers, itemRef } = useItemNavigation() ?? {};
+    const { focusVisible, focusVisibleRef, focusVisibleHandlers } = useFocusVisible({
+        onFocus: (e) => {
+            keyboardNavHandlers?.onFocus(e);
+            onFocus?.(e);
+        },
+        onBlur: (e) => {
+            keyboardNavHandlers?.onBlur(e);
+            onBlur?.(e);
+        },
+    });
+    const { close: closeMenu } = useMenuContext() ?? {};
+    const { active, activeHandlers } = useActive({
+        onKeyDown: (e) => {
+            onKeyDown?.(e);
+            keyboardNavHandlers?.onKeyDown(e);
+        },
+        onKeyUp,
+        onClick: (e) => {
+            onClick?.(e);
+            if (autoClose)
+                closeMenu?.();
+        },
+    });
+    const handleItemRef = useForkRef(ref, focusVisibleRef, itemRef);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getRootProps = (otherProps) => {
+        return {
+            role: 'menuitem',
+            tabIndex: '-1',
+            disabled,
+            ...otherProps,
+            ...focusVisibleHandlers,
+            ...activeHandlers,
+            ref: handleItemRef,
+        };
+    };
+    return { getRootProps, focusVisible, active };
+};
+
+const useVirtualizedMenuItem = (props) => {
+    const { onBlur, onFocus, onKeyDown, onKeyUp, onClick, autoClose, ref } = props;
+    const { keyboardNavHandlers, itemRef } = useItemNavigation() ?? {};
+    const vlItemProps = useVirtualizedItemPropsContext();
+    const { focusVisible, focusVisibleRef, focusVisibleHandlers } = 
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useFocusVisible({
+        onFocus: (e) => {
+            keyboardNavHandlers?.onFocus(e);
+            onFocus?.(e);
+        },
+        onBlur: (e) => {
+            keyboardNavHandlers?.onBlur(e);
+            onBlur?.(e);
+        },
+    });
+    const { close: closeMenu } = useMenuContext() ?? {};
+    const { active, activeHandlers } = useActive({
+        onKeyDown: (e) => {
+            onKeyDown?.(e);
+            keyboardNavHandlers?.onKeyDown(e);
+        },
+        onKeyUp,
+        onClick: (e) => {
+            onClick?.(e);
+            if (autoClose)
+                closeMenu?.();
+        },
+    });
+    const handleItemRef = useForkRef(ref, focusVisibleRef, itemRef);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getRootProps = (otherProps) => {
+        return {
+            role: 'menuitem',
+            tabIndex: -1,
+            ...otherProps,
+            ...focusVisibleHandlers,
+            ...activeHandlers,
+            ...vlItemProps,
+            ref: handleItemRef,
+        };
+    };
+    return { getRootProps, focusVisible, active };
+};
+
+const MenuItem = forwardRef((inProps, ref) => {
+    const props = useThemeProps({ props: inProps, name: 'MenuItem' });
+    const { classes, className, children, selected, disabled, onMouseEnter, onMouseLeave, highlighted = false, focused = false, autoClose = true, autoFocus, ...rest } = props;
+    const cls = useClasses('menu-item', classes, className);
+    const vlItemProps = useVirtualizedItemPropsContext();
+    const isInVlRef = useRef(Boolean(vlItemProps));
+    const useMenuItemHook = (() => {
+        if (isInVlRef.current) {
+            return useVirtualizedMenuItem;
+        }
+        else {
+            return useMenuItem;
+        }
+    })();
+    const itemRef = useRef(null);
+    const handleRef = useForkRef(itemRef, ref);
+    const { getRootProps, focusVisible, active } = useMenuItemHook({
+        ...props,
+        autoClose,
+        ref: handleRef,
+    });
+    const selectable = !(selected === undefined);
+    const selectContextValue = useMenuItemSelectContext();
+    const menuListContextValue = useMenuListContext();
+    const selectMode = selectContextValue
+        ? selectContextValue.selectMode
+        : 'single';
+    const id = useId();
+    const { hover, hoverHandlers } = useHover({ onMouseEnter, onMouseLeave });
+    useNestedMenuItem({ hovered: hover, id });
+    useEffect(() => {
+        if (autoFocus) {
+            itemRef.current?.focus();
+            requestAnimationFrame(() => {
+                if (
+                // jsdom doesn't support scrollIntoView, this avoids users needing to bring their own mock
+                process.env.NODE_ENV === 'test' &&
+                    typeof itemRef.current?.scrollIntoView !== 'function') {
+                    return;
+                }
+                itemRef.current?.scrollIntoView({
+                    block: 'nearest',
+                    inline: 'nearest',
+                });
+            });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return (jsx("div", { className: cls('root', {
+            selectable,
+            selected,
+            focusVisible,
+            disabled,
+            active,
+            highlighted,
+            focused,
+            nowrap: menuListContextValue.nowrap,
+        }), ...getRootProps(rest), ...hoverHandlers, children: jsxs("div", { className: cls('container'), children: [selectable && (jsx("div", { className: cls('select-indicator'), children: selectMode === 'single' ? (jsx("span", { className: cls('select-dot') })) : (jsx(Icon, { symbol: CheckBoldMd, size: "small" })) })), children] }) }));
+});
+MenuItem.displayName = 'SuiMenuItem';
+
+var Action;
+(function (Action) {
+    Action["SELECT"] = "select";
+    Action["DESELECT"] = "deselect";
+})(Action || (Action = {}));
+const useMenuItemSelect = (props) => {
+    const { widget = 'menu', selectMode = 'single', value: valueProp = selectMode === 'single' ? null : [], onChange, onClose, autoFocus: autoFocusProp = true, } = props;
+    const isSingleMode = selectMode === 'single';
+    if (process.env.NODE_ENV !== 'production' &&
+        !isSingleMode &&
+        !Array.isArray(valueProp)) {
+        throw Error('SPRING [useMenuItemSelect]: value must be an array if selectMode is multiple');
+    }
+    const value = valueProp;
+    const getMenuItemProps = useCallback((itemValue) => {
+        let selected;
+        let autoFocus;
+        if (isSingleMode) {
+            selected = value === itemValue;
+            autoFocus = selected;
+        }
+        else {
+            selected = value.includes(itemValue);
+            autoFocus = value[0] === itemValue;
+        }
+        const menuItemRole = selectMode === 'single' ? 'menuitemradio' : 'menuitemcheckbox';
+        // Use appropriate ARIA attributes based on widget type and role:
+        // - For listbox/option pattern: use aria-selected
+        // - For menu with selectable items: use menuitemradio/menuitemcheckbox with aria-checked
+        const ariaProps = widget === 'menu'
+            ? { 'aria-checked': selected }
+            : { 'aria-selected': selected };
+        return {
+            role: widget === 'menu' ? menuItemRole : 'option',
+            ...ariaProps,
+            selected,
+            autoFocus: autoFocusProp && autoFocus,
+        };
+    }, [isSingleMode, selectMode, widget, autoFocusProp, value]);
+    const handleSelect = useEventCallback((itemValue) => {
+        let action = Action.SELECT;
+        if (isSingleMode) {
+            // User clicked on an already selected item
+            if (value === itemValue) {
+                onClose?.();
+            }
+            else {
+                onChange?.(itemValue);
+            }
+        }
+        else {
+            const index = value.indexOf(itemValue);
+            let newValue;
+            if (index >= 0) {
+                action = Action.DESELECT;
+                newValue = [
+                    ...value.slice(0, index),
+                    ...value.slice(index + 1),
+                ];
+            }
+            else {
+                newValue = [...value, itemValue];
+            }
+            onChange?.(newValue, {
+                value: itemValue,
+                action,
+            });
+        }
+    });
+    const contextValue = useMemo(() => ({
+        selectMode,
+        value,
+        handleSelect,
+        getMenuItemProps,
+    }), [getMenuItemProps, handleSelect, selectMode, value]);
+    return {
+        value,
+        contextValue,
+    };
+};
+
+export { Action as A, MenuItem as M, MenuItemSelectContext as a, useMenuItem as b, useMenuItemSelect as c, useVirtualizedMenuItem as d, MenuListContext as e, useMenuListContext as f, useMenuItemSelectContext as u };

package/chunks/useMotionSafeTransition.js

@@ -0,0 +1,13 @@
+import { motionTransition } from '@ringcentral/spring-theme';
+import { u as usePrefersReducedMotion } from './usePrefersReducedMotion.js';
+
+/**
+ * A hook that returns an instant transition if the user has reduced motion enabled.
+ * If reduced motion is not enabled, returns the given motion transition.
+ */
+const useMotionSafeTransition = (transition) => {
+    const prefersReducedMotion = usePrefersReducedMotion();
+    return prefersReducedMotion ? motionTransition.instant : transition;
+};
+
+export { useMotionSafeTransition as u };

package/chunks/useNestedMenuItem.js

@@ -0,0 +1,16 @@
+import { useEffect } from 'react';
+import { u as useNestedMenuContext } from './useNestedParentMenu.js';
+
+const useNestedMenuItem = (props) => {
+    const context = useNestedMenuContext();
+    const { hovered, id } = props;
+    const { registHoveredItem } = context ?? {};
+    useEffect(() => {
+        if (hovered) {
+            return registHoveredItem?.(id);
+        }
+        return undefined;
+    }, [hovered, id, registHoveredItem]);
+};
+
+export { useNestedMenuItem as u };

package/chunks/useNestedParentMenu.js

@@ -0,0 +1,54 @@
+import { createContext, useContext, useRef, useState, useMemo, useEffect, useLayoutEffect } from 'react';
+
+const NestedMenuContext = createContext(null);
+const useNestedMenuContext = () => {
+    return useContext(NestedMenuContext);
+};
+
+const useNestedParentMenu = (props) => {
+    const openedSubMenuSymbolRef = useRef(null);
+    const [hoveredItemId, setHoveredItemId] = useState();
+    const { open } = props;
+    const contextValue = useMemo(() => {
+        return {
+            registHoveredItem: (id) => {
+                setHoveredItemId(id);
+                return () => {
+                    setHoveredItemId((pre) => {
+                        if (pre === id)
+                            return undefined;
+                        return pre;
+                    });
+                };
+            },
+            registOpenedSubMenu: (menuItemSymbol) => {
+                openedSubMenuSymbolRef.current?.closeSubMenu();
+                openedSubMenuSymbolRef.current = menuItemSymbol;
+                return () => {
+                    if (openedSubMenuSymbolRef.current === menuItemSymbol) {
+                        openedSubMenuSymbolRef.current = null;
+                    }
+                };
+            },
+        };
+    }, []);
+    useEffect(() => {
+        const symbol = openedSubMenuSymbolRef.current;
+        // symbol existed means subMenu exited
+        if (symbol && hoveredItemId && hoveredItemId !== symbol.anchorId) {
+            symbol.closeSubMenu();
+        }
+    }, [hoveredItemId]);
+    // Ensure that all menus can be visually closed at the same time
+    useLayoutEffect(() => {
+        if (!open) {
+            openedSubMenuSymbolRef.current?.closeSubMenu();
+        }
+    }, [open]);
+    return {
+        contextValue,
+        getHaveOpenedSubMenu: () => Boolean(openedSubMenuSymbolRef.current),
+    };
+};
+
+export { NestedMenuContext as N, useNestedParentMenu as a, useNestedMenuContext as u };

package/chunks/usePrefersReducedMotion.js

@@ -0,0 +1,42 @@
+import { useGlobalListener } from '@ringcentral/spring-base';
+import { MotionConfigContext } from 'framer-motion';
+import { useState, useContext } from 'react';
+
+/**
+ * in all component that uses this hook, we always use same instance of MediaQueryList
+ * so we can cache the instance here
+ */
+let instance;
+const getPrefersReducedMotionMediaQuery = () => {
+    if (!instance ||
+        // in test environment, we need to reassign the instance to the window object
+        process.env.NODE_ENV === 'test') {
+        instance = window?.matchMedia?.('(prefers-reduced-motion)');
+    }
+    return instance;
+};
+const usePrefersReducedMotion = () => {
+    const mediaQuery = getPrefersReducedMotionMediaQuery();
+    const [shouldReduceMotion, setShouldReduceMotion] = useState(mediaQuery?.matches || false);
+    const context = useContext(MotionConfigContext);
+    useGlobalListener('change', ((event) => {
+        setShouldReduceMotion(event.matches);
+    }), {
+        target: mediaQuery,
+        customKey: 'prefers-reduced-motion',
+    });
+    /**
+     * As we're determining the reduced motion state ourselves after the initial mount,
+     * we need to check the MotionConfigContext to see how the prefers-reduced-motion
+     * state should be handled.
+     */
+    if (context.reducedMotion === 'always') {
+        return true;
+    }
+    else if (context.reducedMotion === 'never') {
+        return false;
+    }
+    return shouldReduceMotion;
+};
+
+export { usePrefersReducedMotion as u };

package/chunks/useTooltipForceHide.js

@@ -0,0 +1,31 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+/**
+ * store tooltip open state when forceHide is true and set tooltip open to false
+ * restore open state once forceHide changed to false
+ */
+const useTooltipForceHide = (forceHide) => {
+    const [open, setOpen] = useState(false);
+    const openStateStore = useRef();
+    const onOpenStateChange = useCallback((event, isOpen) => {
+        if (openStateStore.current !== undefined) {
+            openStateStore.current = isOpen;
+        }
+        else {
+            setOpen(isOpen);
+        }
+    }, []);
+    useEffect(() => {
+        if (open && forceHide) {
+            setOpen(false);
+            openStateStore.current = open;
+        }
+        if (!forceHide && openStateStore.current !== undefined) {
+            setOpen(openStateStore.current);
+            openStateStore.current = undefined;
+        }
+    }, [open, forceHide]);
+    return { open, onOpenStateChange };
+};
+
+export { useTooltipForceHide as u };

package/chunks/useTrayNavigate.js

@@ -0,0 +1,151 @@
+import { jsx } from 'react/jsx-runtime';
+import { useState, useMemo, createContext, useContext, forwardRef, useRef, useImperativeHandle, useEffect } from 'react';
+import { useControlled, useEventCallback, logInDev, useClasses, useForkRef } from '@ringcentral/spring-base';
+import { useThemeProps, motionTransition } from '@ringcentral/spring-theme';
+import { AnimatePresence, motion } from 'framer-motion';
+import './Icon.js';
+import { u as useMotionSafeTransition } from './useMotionSafeTransition.js';
+
+const useTray = (parameters) => {
+    const { value: valueProp, defaultValue, onChange, containerRef } = parameters;
+    const [value, setValue] = useControlled({
+        controlled: valueProp,
+        default: defaultValue,
+        name: 'useTray',
+        state: 'value',
+    });
+    if (value === undefined) {
+        throw new Error('Should set default TrayPanel using defaultValue (not controlled) or value (controlled)');
+    }
+    const [stack, setStack] = useState([value]);
+    const [direction, setDirection] = useState('right');
+    const updateValue = (e, newValue) => {
+        setValue(newValue);
+        onChange?.(e, newValue);
+        if (stack.includes(newValue)) {
+            setStack([...stack.slice(0, stack.indexOf(newValue) + 1)]);
+            setDirection('left');
+        }
+        else {
+            setStack([...stack, newValue]);
+            setDirection('right');
+        }
+    };
+    const navigateTo = useEventCallback((newValue, event = null) => {
+        let handledValue = newValue;
+        if (handledValue === null && stack.length === 1) {
+            if (process.env.NODE_ENV !== 'production') {
+                logInDev({
+                    scope: 'useTray',
+                    message: 'No TrayPanel left to return to',
+                });
+            }
+            return;
+        }
+        if (handledValue === null) {
+            // return to previous TrayPanel when value is false
+            handledValue = stack[stack.length - 2];
+        }
+        containerRef.current?.focus();
+        updateValue(event, handledValue);
+    });
+    const trayContextValue = useMemo(() => {
+        return {
+            value,
+            navigateTo,
+            direction,
+            containerRef,
+        };
+    }, [value, navigateTo, direction, containerRef]);
+    return {
+        trayContextValue,
+    };
+};
+
+const TrayContext = createContext(null);
+const useTrayContext = () => useContext(TrayContext);
+
+const Tray = forwardRef((inProps, ref) => {
+    const props = useThemeProps({ props: inProps, name: 'Tray' });
+    const { classes, children, value, defaultValue, onChange, actions, className, ...rest } = props;
+    const cls = useClasses('tray', classes, className);
+    const rootRef = useRef(null);
+    const handleRootRef = useForkRef(ref, rootRef);
+    const { trayContextValue } = useTray({
+        value,
+        defaultValue,
+        onChange,
+        containerRef: rootRef,
+    });
+    const { navigateTo } = trayContextValue;
+    useImperativeHandle(actions, () => ({
+        navigateTo,
+    }), [navigateTo]);
+    return (jsx("div", { className: cls('root'), ref: handleRootRef, ...rest, tabIndex: -1, children: jsx(TrayContext.Provider, { value: trayContextValue, children: children }) }));
+});
+Tray.displayName = 'SuiTray';
+
+const useTrayPanel = (parameters) => {
+    const { value } = parameters;
+    const context = useTrayContext();
+    if (context === null) {
+        throw new Error('No TrayContext provided, must be used within a Tray');
+    }
+    const activated = value === context.value;
+    return {
+        activated,
+        containerRef: context.containerRef,
+        direction: context.direction,
+    };
+};
+
+const TrayPanel = forwardRef((inProps, ref) => {
+    const props = useThemeProps({ props: inProps, name: 'TrayPanel' });
+    const { children, classes, className } = props;
+    const { activated, containerRef, direction } = useTrayPanel(props);
+    const [display, setDisplay] = useState(activated);
+    useEffect(() => {
+        if (activated) {
+            setDisplay(true);
+        }
+    }, [activated]);
+    const cls = useClasses('tray-panel', classes, className);
+    const transition = useMotionSafeTransition(motionTransition['spring-01-fast']);
+    return (jsx(AnimatePresence, { initial: false, children: display && (jsx(motion.div, { ref: ref, className: cls('root', { activated }), "data-activated": activated, transition: transition, initial: 'enter', animate: activated ? 'center' : 'exit', onAnimationComplete: () => {
+                !activated && setDisplay(false);
+            }, variants: {
+                enter: {
+                    height: containerRef.current?.querySelector('[data-activated="false"]')?.offsetHeight,
+                    transform: direction === 'right'
+                        ? 'translateX(100%)'
+                        : 'translateX(-100%)',
+                },
+                center: {
+                    height: 'auto',
+                    transform: 'translateX(0%)',
+                },
+                exit: {
+                    transform: direction === 'right'
+                        ? 'translateX(-100%)'
+                        : 'translateX(100%)',
+                },
+            }, children: children })) }));
+});
+TrayPanel.displayName = 'SuiTrayPanel';
+
+const useTrayNavigate = () => {
+    const context = useTrayContext();
+    if (context === null) {
+        throw new Error('No TrayContext provided, must be used within a Tray');
+    }
+    const { navigateTo } = context;
+    const back = (event = null) => {
+        context.navigateTo(null, event);
+    };
+    return {
+        navigateTo,
+        back,
+    };
+};
+
+export { Tray as T, TrayContext as a, TrayPanel as b, useTray as c, useTrayNavigate as d, useTrayPanel as e, useTrayContext as u };

package/chunks/withTooltip.js

@@ -0,0 +1,15 @@
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef } from 'react';
+import { T as Tooltip } from './Tooltip.js';
+
+function withTooltip(Component) {
+    return forwardRef((props, ref) => {
+        const { TooltipProps, ...rest } = props;
+        const content = jsx(Component, { ...rest, ref: ref });
+        if (!TooltipProps)
+            return content;
+        return jsx(Tooltip, { ...TooltipProps, children: content });
+    });
+}
+
+export { withTooltip as w };