@fjyueke/arco-mcp 1.0.0

package/metaData/components/popover/example/menu.tsx

@@ -0,0 +1,145 @@
+import { cls } from '@arco-design/mobile-utils';
+import React, {
+    useContext,
+    useMemo,
+    useState,
+    useRef,
+    forwardRef,
+    useImperativeHandle,
+    Ref,
+} from 'react';
+import { GlobalContext } from '../context-provider';
+import { PopoverMenuItem, PopoverMenuProps, PopoverProps, PopoverRef } from './type';
+import { useUpdateEffect } from '../_helpers';
+
+export function componentGenerator<
+    P extends PopoverProps = PopoverProps,
+    R extends PopoverRef = PopoverRef,
+>(Comp: React.ForwardRefExoticComponent<P & React.RefAttributes<R>>) {
+    return forwardRef((props: PopoverMenuProps, ref: Ref<R | null>) => {
+        const {
+            menu,
+            menuLayout = 'vertical',
+            onSelect,
+            onClickMenuItem,
+            className = '',
+            useClickStatus = false,
+            clickStatusDuration = 300,
+            clickSelfToClose = true,
+            touchSelfToClose = props.touchToClose === void 0 ? false : props.touchToClose,
+            defaultVisible = false,
+            visible,
+            onChange,
+            ...restProps
+        } = props;
+        const { prefixCls } = useContext(GlobalContext);
+        const [activeIndex, setActiveIndex] = useState(-1);
+        const activeTimer = useRef(0);
+        const formattedMenu: PopoverMenuItem[] = useMemo(() => {
+            return menu.map(item => {
+                if (typeof item === 'string') {
+                    return {
+                        text: item,
+                    };
+                }
+                return item;
+            });
+        }, [menu]);
+
+        const [visibleState, setVisibleState] = useState(
+            visible === void 0 ? defaultVisible : visible,
+        );
+        useUpdateEffect(() => {
+            setVisibleState(Boolean(visible));
+        }, [visible]);
+
+        const popoverRef = useRef<R | null>(null);
+
+        useImperativeHandle(ref, () => popoverRef.current!);
+
+        const onVisibleChange = newVisible => {
+            const handleVisibleChange = () => {
+                if (onChange && typeof onChange === 'function') {
+                    onChange(newVisible);
+                }
+                if (visible === void 0) {
+                    setVisibleState(newVisible);
+                }
+            };
+
+            // 如果设置了点击效果则延时回调onChange函数，留出点击效果的时间
+            // @en If the click effect is set, the onChange function is delayed and called back, leaving time for the click effect
+            if (!newVisible && useClickStatus) {
+                window.setTimeout(handleVisibleChange, Math.max(0, clickStatusDuration - 300));
+            } else {
+                handleVisibleChange();
+            }
+        };
+
+        const content = useMemo(
+            () => (
+                <div className={cls(`${prefixCls}-popover-menu-content`, `${menuLayout}-menu`)}>
+                    {formattedMenu.map((item, index) => {
+                        const defaultValue =
+                            typeof item.text === 'string' ? item.text : `menu_item_${index}`;
+                        const { text, value = defaultValue, disabled = false, icon } = item;
+                        return (
+                            <div
+                                className={cls(`${prefixCls}-popover-menu-item`, {
+                                    disabled,
+                                    active: activeIndex === index,
+                                })}
+                                key={value}
+                                onTouchStart={() => {
+                                    if (useClickStatus && !disabled) {
+                                        clearTimeout(activeTimer.current);
+                                        setActiveIndex(index);
+                                        activeTimer.current = window.setTimeout(() => {
+                                            setActiveIndex(-1);
+                                            activeTimer.current = 0;
+                                        }, clickStatusDuration);
+                                    }
+                                }}
+                                onClick={() => {
+                                    onClickMenuItem && onClickMenuItem(value, menu[index]);
+                                    if (disabled) return;
+                                    onSelect && onSelect(value, menu[index]);
+                                }}
+                            >
+                                {icon && (
+                                    <div className={cls(`${prefixCls}-popover-menu-icon`)}>
+                                        {icon}
+                                    </div>
+                                )}
+                                <div className={cls(`${prefixCls}-popover-menu-text`)}>{text}</div>
+                            </div>
+                        );
+                    })}
+                </div>
+            ),
+            [
+                prefixCls,
+                menuLayout,
+                formattedMenu,
+                activeIndex,
+                useClickStatus,
+                clickStatusDuration,
+                onClickMenuItem,
+                onSelect,
+            ],
+        );
+
+        return (
+            <Comp
+                ref={popoverRef}
+                visible={visibleState}
+                clickSelfToClose={clickSelfToClose}
+                touchSelfToClose={touchSelfToClose}
+                onChange={onVisibleChange}
+                {...(restProps as P)}
+                content={content}
+                className={cls(className, `${prefixCls}-popover-menu`)}
+            />
+        );
+    });
+}

package/metaData/components/popover/example/popover-inner.tsx

@@ -0,0 +1,147 @@
+import React, { forwardRef, Ref, useImperativeHandle, useRef, useContext, useEffect } from 'react';
+import { cls } from '@arco-design/mobile-utils';
+import IconClose from '../icon/IconClose';
+import { getStyleWithVendor, useMountedState } from '../_helpers';
+import { PopoverInnerProps, PopoverInnerRef } from './type';
+import { GlobalContext } from '../context-provider';
+
+export const PopoverInner = forwardRef((props: PopoverInnerProps, ref: Ref<PopoverInnerRef>) => {
+    const { prefixCls } = useContext(GlobalContext);
+    const {
+        className,
+        needShadow,
+        content,
+        direction,
+        position,
+        minWidth,
+        maxWidth,
+        arrowWidth,
+        transformOrigin,
+        mode,
+        showCloseIcon = false,
+        textSuffix = null,
+        renderArrow,
+        onClickCloseIcon,
+        onClickTextSuffix,
+    } = props;
+    const domRef = useRef<HTMLDivElement>(null);
+    const contentRef = useRef<HTMLDivElement>(null);
+    const [show, setShow] = useMountedState(false);
+
+    useImperativeHandle(ref, () => ({
+        dom: domRef.current,
+        content: contentRef.current,
+    }));
+
+    useEffect(() => {
+        const { top, bottom, height, left, width } = position;
+        if (left || width || top || height || bottom) {
+            if (!show) {
+                setTimeout(() => {
+                    setShow(() => {
+                        // bugfix:
+                        // 外层CSSTransition使用dom API而非通过react className属性修改class
+                        // 如果内部通过react className属性动态修改class会覆盖CSSTransition的设置，导致CSSTransition enter相关的class无法应用到组件
+                        domRef.current?.classList.add('show');
+                        return true;
+                    });
+                }, 0);
+            }
+        }
+    }, [position, show]);
+
+    /**
+     * 计算容器的样式
+     * @en Calculate the stylesheet of the container
+     */
+    const getWrapperStyle = () => {
+        const { top, bottom, height, left } = position;
+
+        const obj: React.CSSProperties = {
+            height: `${height}px`,
+            left: `${left}px`,
+            minWidth,
+            maxWidth,
+        };
+
+        if (top) {
+            obj.top = `${top}px`;
+        } else if (bottom) {
+            obj.bottom = `${bottom}px`;
+        }
+        // 用于执行缩放动画
+        // @en Used to perform zoom animations
+        obj.transformOrigin = `${transformOrigin.x} ${transformOrigin.y}`;
+        return getStyleWithVendor(obj);
+    };
+
+    /**
+     * 计算icon的样式
+     * @en Calculate the stylesheet of the icon
+     */
+    const getArrowStyle = () => {
+        const { arrowLeft } = position;
+        return {
+            width: arrowWidth,
+            height: arrowWidth,
+            marginLeft: arrowLeft ? `${arrowLeft}px` : null,
+            marginRight: arrowLeft ? `${arrowLeft}px` : null,
+        } as React.CSSProperties;
+    };
+
+    return (
+        <div
+            ref={domRef}
+            className={cls(
+                `${prefixCls}-popover-inner`,
+                'popover-inner',
+                'all-border-box',
+                `${mode}-mode`,
+                className,
+                {
+                    'with-shadow': needShadow,
+                    'with-suffix': showCloseIcon || textSuffix,
+                    'custom-content': typeof content !== 'string',
+                },
+            )}
+            style={getWrapperStyle()}
+        >
+            <div className="popover-bg">
+                {renderArrow ? (
+                    renderArrow({ arrowWidth, arrowLeft: position.arrowLeft, direction })
+                ) : (
+                    <div className={`popover-arrow ${direction}`} style={getArrowStyle()}>
+                        <div className="popover-arrow-content" />
+                    </div>
+                )}
+            </div>
+            <div
+                className={cls('popover-content', direction, {
+                    'show-close-icon': showCloseIcon,
+                })}
+                ref={contentRef}
+            >
+                {typeof content === 'string' ? (
+                    <>
+                        <div className="content-text">{content}</div>
+                        {showCloseIcon && (
+                            <>
+                                <div className="icon-divider" />
+                                <div className="text-close-icon" onClick={onClickCloseIcon}>
+                                    <IconClose />
+                                </div>
+                            </>
+                        )}
+                        {textSuffix && (
+                            <div className="text-suffix" onClick={onClickTextSuffix}>
+                                {textSuffix}
+                            </div>
+                        )}
+                    </>
+                ) : (
+                    content
+                )}
+            </div>
+        </div>
+    );
+});

package/metaData/components/popover/example/popover.tsx

@@ -0,0 +1,268 @@
+import React, {
+    forwardRef,
+    Ref,
+    useImperativeHandle,
+    useRef,
+    useState,
+    useContext,
+    useEffect,
+} from 'react';
+import { cls } from '@arco-design/mobile-utils';
+import { GlobalContext } from '../context-provider';
+import { PopoverInner } from './popover-inner';
+import Transition from '../transition';
+import { PopoverRef, PopoverProps, PopoverInnerRef } from './type';
+import { useEvent, usePosition } from './hooks';
+import Portal from '../portal';
+
+export const Popover = forwardRef((props: PopoverProps, ref: Ref<PopoverRef>) => {
+    const {
+        className = '',
+        innerPopoverClassName = '',
+        style = {},
+        theme = 'black',
+        needShadow = false,
+        content = '',
+        transitionTimeout = 300,
+        minWidth = '10px',
+        maxWidth = '90vw',
+        transitionName = 'fade',
+        clickSelfToClose = true,
+        touchSelfToClose = props.touchToClose === void 0 ? false : props.touchToClose,
+        defaultVisible = false,
+        visible,
+        children,
+        bordered = props.theme === 'white',
+        showCloseIcon = false,
+        textSuffix = null,
+        mode = 'follow',
+        showMask = false,
+        maskTransitionTimeout = { enter: 450, exit: 240 },
+        renderArrow,
+        onChange,
+        onClickCloseIcon,
+        onClickTextSuffix,
+        onClickMask,
+    } = props;
+    const { prefixCls } = useContext(GlobalContext);
+    const [visibleState, setVisibleState] = useState(false);
+    const visibleRef = useRef(visibleState);
+    const wrapperRef = useRef<HTMLDivElement | null>(null);
+    const childRef = useRef<HTMLDivElement | null>(null);
+    const popoverRef = useRef<PopoverInnerRef | null>(null);
+    const transitionNodeRef = useRef<HTMLDivElement | null>(null);
+    const maskRef = useRef<HTMLDivElement | null>(null);
+    const {
+        direction,
+        position,
+        isCalcPosition,
+        transformOrigin,
+        computedChildAndPopoverOffset,
+        arrowWidth,
+        resetPosition,
+        adjustVerticalDirection,
+    } = usePosition(props, popoverRef, childRef, wrapperRef);
+
+    /**
+     * 气泡状态切换
+     * @en Bubble state toggle
+     */
+    const onVisibleChange = (newVisible = true) => {
+        // 为了防止退出中有缩放动画影响气泡位置计算，在退出动画结束前不可切换到展示气泡状态
+        // @en In order to prevent the zoom animation in the exit from affecting the calculation of the bubble position, it is not possible to switch to the display bubble state before the exit animation ends.
+        if (newVisible && !isCalcPosition) {
+            return;
+        }
+        onChange?.(newVisible);
+        if (visible === void 0) {
+            setVisibleState(newVisible);
+        }
+    };
+
+    const { popoverDisappear, mayAddEventOnBody, startCloseTimer, mayRemoveEventListenerOnBody } =
+        useEvent(
+            props,
+            wrapperRef,
+            popoverRef,
+            visibleRef,
+            onVisibleChange,
+            adjustVerticalDirection,
+        );
+
+    useImperativeHandle(ref, () => ({
+        dom: wrapperRef.current,
+        child: childRef.current,
+        innerPopover: popoverRef.current,
+        innerPopoverDom: popoverRef.current?.dom || null,
+        updatePosition,
+    }));
+
+    useEffect(() => {
+        if (defaultVisible || visible) {
+            setVisibleState(true);
+        }
+
+        return () => {
+            mayRemoveEventListenerOnBody();
+        };
+    }, []);
+
+    useEffect(() => {
+        if (visible !== void 0) {
+            setVisibleState(Boolean(visible));
+        }
+    }, [visible]);
+
+    useEffect(() => {
+        // 非 visibleState 变化引起的回调，仅用于更新位置
+        // @en Callbacks not caused by visibleState changes, only used to update the position
+        if (visibleRef.current) {
+            computedChildAndPopoverOffset();
+        }
+    }, [children, content, direction, mode]);
+
+    useEffect(() => {
+        visibleState && showPopover();
+        visibleRef.current = visibleState;
+        if (!visibleState) {
+            mayRemoveEventListenerOnBody();
+            setTimeout(() => {
+                !visibleRef.current && resetPosition();
+            }, (typeof transitionTimeout === 'object' ? transitionTimeout.exit : transitionTimeout) || 300);
+        }
+    }, [visibleState]);
+
+    function showPopover() {
+        startCloseTimer();
+        setTimeout(mayAddEventOnBody, 0);
+
+        // 为了防止缩放动画影响气泡位置计算，气泡漏出阶段不重新计算位置
+        // @en In order to prevent the zoom animation from affecting the bubble position calculation, the bubble leakage stage does not recalculate the position
+        if (!isCalcPosition) {
+            return;
+        }
+
+        // 异步计算气泡位置，等待气泡渲染
+        // @en Calculate the bubble position asynchronously and wait for the bubble to render
+        setTimeout(() => {
+            computedChildAndPopoverOffset();
+        }, 0);
+    }
+
+    function updatePosition() {
+        if (!visibleState) return;
+        computedChildAndPopoverOffset();
+    }
+
+    function onClickWrapper() {
+        const visibleRefValue = visibleRef.current;
+        if (!visibleRefValue) {
+            onVisibleChange(true);
+            return;
+        }
+        if (visibleRefValue && clickSelfToClose && !touchSelfToClose) {
+            popoverDisappear();
+        }
+    }
+
+    function onTouchWrapper() {
+        // 仅处理气泡消失，气泡出现交给onClick来处理
+        // @en Only the disappearance of the bubble is processed, and the appearance of the bubble is handed over to onClick for processing
+        if (touchSelfToClose && visibleRef.current) {
+            popoverDisappear();
+        }
+    }
+
+    const renderInnerPopover = () => (
+        <PopoverInner
+            className={cls(`${theme}-theme`, innerPopoverClassName, {
+                bordered,
+            })}
+            ref={ele => {
+                popoverRef.current = ele;
+                transitionNodeRef.current = ele?.dom!;
+            }}
+            direction={direction}
+            minWidth={minWidth}
+            maxWidth={maxWidth}
+            position={position}
+            arrowWidth={arrowWidth}
+            transformOrigin={transformOrigin}
+            needShadow={needShadow}
+            content={content}
+            mode={mode}
+            showCloseIcon={showCloseIcon}
+            textSuffix={textSuffix}
+            renderArrow={renderArrow}
+            onClickCloseIcon={onClickCloseIcon}
+            onClickTextSuffix={onClickTextSuffix}
+        />
+    );
+
+    const renderPopover = () => {
+        return (
+            <Portal
+                getContainer={() => {
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    return mode === 'global' ? document.body : wrapperRef.current!;
+                }}
+            >
+                {visibleState && isCalcPosition && renderInnerPopover()}
+                <Transition
+                    in={visibleState && !isCalcPosition}
+                    timeout={transitionTimeout}
+                    type={transitionName}
+                    nodeRef={transitionNodeRef}
+                    mountOnEnter
+                    unmountOnExit
+                >
+                    {renderInnerPopover()}
+                </Transition>
+            </Portal>
+        );
+    };
+
+    return (
+        <>
+            {showMask && (
+                <Portal>
+                    <Transition
+                        in={visibleState && !isCalcPosition}
+                        timeout={maskTransitionTimeout}
+                        nodeRef={maskRef}
+                        type="fade"
+                        mountOnEnter
+                        unmountOnExit
+                    >
+                        <div
+                            className={`${prefixCls}-popover-mask`}
+                            onClick={onClickMask}
+                            ref={maskRef}
+                        />
+                    </Transition>
+                </Portal>
+            )}
+            <div
+                className={cls(
+                    `${prefixCls}-popover`,
+                    className,
+                    `${theme}-theme`,
+                    `${mode}-mode`,
+                    {
+                        bordered,
+                        'custom-content': typeof content !== 'string',
+                    },
+                )}
+                style={style}
+                ref={wrapperRef}
+                onClick={onClickWrapper}
+                onTouchStart={onTouchWrapper}
+            >
+                {renderPopover()}
+                <div ref={childRef} className="popover-child-inner">
+                    {children}
+                </div>
+            </div>
+        </>
+    );
+});

package/metaData/components/popup/doc.md

@@ -0,0 +1,101 @@
+### 反馈
+
+# 弹出层 Popup
+
+基于模态弹窗的的全屏菜单，支持各个方向。默认做了防滚动穿透处理，如果弹层内容中需要滚动，则需将滚动容器传入`getScrollContainer`属性以在未滚动到顶部或底部时释放滚动。
+
+======
+
+> 属性/Props
+
+|参数|描述|类型|默认值|
+|----------|-------------|------|------|
+|direction|菜单滑出方向|"left" \| "right" \| "top" \| "bottom"|"bottom"|
+|needBottomOffset|从底部滑出的菜单内容是否适配ipx底部|boolean|false|
+|translateZ|\[即将废弃\] 开启translateZ强制提升|boolean|false|
+|maskTransitionTimeout|菜单蒙层动画时长|number \| \{ appear?: number; enter?: number; exit?: number; \}|{ enter: 450, exit: 240 }|
+|contentTransitionTimeout|菜单内容动画时长|number \| \{ appear?: number; enter?: number; exit?: number; \}|{ enter: 450, exit: 240 }|
+|contentTransitionType|内容过渡动画类名|string|\`slide-from-${props.direction}\`|
+|className|自定义类名|string|-|
+|maskClass|自定义蒙层类名|string|-|
+|maskStyle|自定义蒙层样式|CSSProperties|-|
+|contentClass|自定义内容类名|string|-|
+|contentStyle|自定义内容样式|CSSProperties|-|
+|visible|是否展示菜单（受控）|boolean|必填|
+|close|关闭菜单方法|(e: MouseEvent\<HTMLElement, MouseEvent\>) =\> void|必填|
+|maskTransitionType|蒙层过渡动画类名|string|"fade"|
+|contentTransitionVarType|内容过渡动画类名变量标识|string|-|
+|children|菜单内部内容|ReactNode|-|
+|maskClosable|点击蒙层是否关闭菜单|boolean|true|
+|animatingClosable|执行进场动画时点击蒙层是否可关闭菜单|boolean|false|
+|mountOnEnter|是否在打开菜单时再加载内容|boolean|true|
+|unmountOnExit|是否在退出时卸载内容|boolean|true|
+|orientationDirection|transform方向，用于通过transform模拟横屏的情况|"left" \| "right" \| "top" \| "bottom"|"top"|
+|preventBodyScroll|弹窗打开时是否禁止body的滚动|boolean|true|
+|initialBodyOverflow|页面初始 overflow 状态，即关闭弹窗时 overflow 应该还原的状态|string|第一个全屏组件（弹窗、toast等）打开时页面overflow值|
+|gestureOutOfControl|是否禁用滚动容器手势判断，禁用后交给业务方自己判断|boolean|false|
+|onClose|关闭后回调（动画执行完毕）|(scene?: string) =\> void|-|
+|onOpen|打开后回调（动画执行完毕）|() =\> void|-|
+|onMaskClick|点击蒙层回调，maskClosable=false时也会触发|() =\> void|-|
+|onTouchMove|弹窗的touchmove回调|(e: TouchEvent, prevented: boolean, direction: "x" \| "y") =\> void|-|
+|onPreventTouchMove|非滚动区域或滚动到顶部及底部时的触摸事件回调|(e: TouchEvent, direction: "x" \| "y") =\> void|-|
+|getContainer|获取挂载容器|() =\> HTMLElement|-|
+|getScrollContainer|内容内部滚动区域容器，在该容器中未滚动到顶部或底部时会释放滚动|() =\> HTMLElement \| HTMLElement\[\]|-|
+
+> 引用/Refs
+
+|参数|描述|类型|
+|----------|-------------|------|
+|dom|最外层元素 DOM|HTMLDivElement|
+|mask|蒙层 DOM|HTMLDivElement|
+|content|内容 DOM|HTMLDivElement|
+|setCloseScene|在关闭弹窗前修改 onClose 的 scene 参数值|(scene: string) =\> void|
+
+> 方法/Methods
+
+|方法名|描述|类型|
+|----------|-------------|------|
+|open|打开弹出层|(config: PopupProps) =\> \{ close: () =\> void; update: (newConfig: PopupProps) =\> void; \}|
+
+> DirectionType
+
+```
+"left" | "right" | "top" | "bottom"
+```
+
+> GlobalContextParams
+
+|参数|描述|类型|默认值|
+|----------|-------------|------|------|
+|prefixCls|组件类名前缀|string|"arco"|
+|system|手动控制当前所在系统，传入后将直接使用传入的值，ssr场景需指定系统初始值时适用|"" \| "pc" \| "android" \| "ios"|""|
+|useDarkMode|是否监听系统原生的暗黑模式变化(prefers\-color\-scheme: dark)以判断是否切为暗黑模式|boolean|false|
+|isDarkMode|是否处于暗黑模式，指定后以指定的值为准|boolean|false|
+|darkModeSelector|当处于暗黑模式时，body上挂载的类名，为空值时不挂载类名|string|"arco-theme-dark"|
+|theme|主题变量，传入后将在线替换css变量，需设置less变量 @use\-css\-vars: 1|Record\<string, string\>|-|
+|locale|国际化语言包配置|ILocale|-|
+|useRtl|是否使用Rtl模式|boolean|false|
+|onDarkModeChange|当系统原生暗黑模式发生变化时触发，useDarkMode=true 时有效|(isDark: boolean) =\> void|-|
+|createRoot|React19 修改了 createRoot 的引入路径，导致组件内部无法直接引入（低react版本会找不到模块）。因此使用 react 19 的用户需从外部传入 createRoot 方法|CreateRootFnType|-|
+
+> ILocale
+
+|参数|描述|类型|
+|----------|-------------|------|
+|locale|语言类型|string|
+|LoadMore|-|\{ loadMoreText: string; loadingText: string; noDataText: string; failLoadText: string; prepareScrollText: string; prepareClickText: string; \}|
+|Picker|-|\{ okText: string; cancelText: string; \}|
+|Tag|-|\{ addTag: string; \}|
+|Dialog|-|\{ okText: string; cancelText: string; \}|
+|SwipeLoad|-|\{ normalText: string; activeText: string; \}|
+|PullRefresh|-|\{ loadingText: string; pullingText: string; finishText: string; loosingText: string; \}|
+|DropdownMenu|-|\{ select: string; \}|
+|Pagination|-|\{ previousPage: string; nextPage: string; \}|
+|Image|-|\{ loadError: string; \}|
+|ImagePicker|-|\{ loadError: string; \}|
+|SearchBar|-|\{ placeholder: string; cancelBtn: string; \}|
+|Stepper|-|\{ minusButtonName: string; addButtonName: string; \}|
+|Keyboard|-|\{ confirm: string; \}|
+|Form|-|\{ required: string; type: \{ email: string; url: string; string: string; number: string; array: string; object: string; boolean: string; \}; number: \{ min: string; max: string; equal: string; range: string; positive: string; negative: string; \}; \.\.\. 4 more \.\.\.; pickerDefaultHint: string; \}|
+|NavBar|-|\{ backBtnAriaLabel: string; \}|
+|Uploader|-|\{ uploadBtn: string; retryUpload: string; \}|