@nocobase/flow-engine 2.1.0-alpha.4 → 2.1.0-alpha.45

package/src/components/dnd/index.tsx

@@ -8,8 +8,10 @@
  */
 
 import { DragOutlined } from '@ant-design/icons';
+import type { Modifier } from '@dnd-kit/core';
 import { DndContext, DndContextProps, DragOverlay, useDraggable, useDroppable } from '@dnd-kit/core';
-import React, { FC, useState } from 'react';
+import type { Transform } from '@dnd-kit/utilities';
+import React, { FC, useCallback, useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { FlowModel } from '../../models';
 import { useFlowEngine } from '../../provider';
@@ -19,18 +21,229 @@ export * from './findModelUidPosition';
 export * from './gridDragPlanner';
 
 export const EMPTY_COLUMN_UID = 'EMPTY_COLUMN';
+export const TOOLBAR_DRAG_ACTIVITY_EVENT = 'nb-toolbar-drag-activity';
+const TOOLBAR_DRAG_ANCHOR_EVENT = 'nb-toolbar-drag-anchor';
+const MENU_SUBMENU_POPUP_SELECTOR = '.ant-menu-submenu-popup';
+
+type ToolbarDragAnchorPoint = {
+  x: number;
+  y: number;
+};
+
+type ToolbarDragAnchorDetail = {
+  modelUid: string;
+  point: ToolbarDragAnchorPoint | null;
+};
+
+export const resolveOverlayAnchorTransform = ({
+  activeId,
+  active,
+  transform,
+  activeNodeRect,
+  dragAnchorPoint,
+}: {
+  activeId: string | null;
+  active: { id: string | number } | null | undefined;
+  transform: Transform;
+  activeNodeRect: { top: number; left: number } | null;
+  dragAnchorPoint: ToolbarDragAnchorPoint | null;
+}): Transform => {
+  if (!activeId || active?.id !== activeId || !dragAnchorPoint || !activeNodeRect) {
+    return transform;
+  }
+
+  return {
+    ...transform,
+    x: transform.x + dragAnchorPoint.x - activeNodeRect.left,
+    y: transform.y + dragAnchorPoint.y - activeNodeRect.top,
+  };
+};
+
+const resolveDraggableHostNode = (activatorNode: HTMLElement | null) => {
+  const ownerDocument = activatorNode?.ownerDocument;
+  const floatToolbarContainer = activatorNode?.closest<HTMLElement>('.nb-toolbar-container[data-model-uid]');
+  const toolbarModelUid = floatToolbarContainer?.getAttribute('data-model-uid');
+
+  if (!ownerDocument || !toolbarModelUid) {
+    return activatorNode;
+  }
+
+  const matchedHosts = Array.from(
+    ownerDocument.querySelectorAll<HTMLElement>(
+      `[data-has-float-menu="true"][data-float-menu-model-uid="${toolbarModelUid}"]`,
+    ),
+  );
+  const popupRoot = floatToolbarContainer?.closest<HTMLElement>(MENU_SUBMENU_POPUP_SELECTOR);
+
+  if (popupRoot) {
+    return (
+      matchedHosts.find((hostNode) => hostNode.closest(MENU_SUBMENU_POPUP_SELECTOR) === popupRoot) || activatorNode
+    );
+  }
+
+  return (
+    matchedHosts.find((hostNode) => !hostNode.closest(MENU_SUBMENU_POPUP_SELECTOR)) || matchedHosts[0] || activatorNode
+  );
+};
 
 // 可拖拽图标组件
-export const DragHandler: FC<{ model: FlowModel; children: React.ReactNode }> = ({
+export const DragHandler: FC<{ model: FlowModel; children?: React.ReactNode }> = ({
   model,
   children = <DragOutlined />,
 }) => {
-  const { attributes, listeners, setNodeRef } = useDraggable({ id: model.uid });
+  const { attributes, isDragging, listeners, setActivatorNodeRef, setNodeRef } = useDraggable({ id: model.uid });
+  const dragHandlerRef = useRef<HTMLSpanElement | null>(null);
+  const draggableNodeRef = useRef<HTMLElement | null>(null);
+  const pointerPressCleanupRef = useRef<(() => void) | null>(null);
+  const isDraggingRef = useRef(isDragging);
+  const isPointerPressActiveRef = useRef(false);
+  const isToolbarDragActiveRef = useRef(false);
+  const syncDraggableNodeRef = useCallback(
+    (activatorNode: HTMLElement | null) => {
+      const nextNode = resolveDraggableHostNode(activatorNode);
+
+      if (draggableNodeRef.current === nextNode) {
+        return;
+      }
+
+      draggableNodeRef.current = nextNode;
+      setNodeRef(nextNode);
+    },
+    [setNodeRef],
+  );
+  const setDragHandlerNodeRef = useCallback(
+    (node: HTMLSpanElement | null) => {
+      dragHandlerRef.current = node;
+      setActivatorNodeRef(node);
+      syncDraggableNodeRef(node);
+    },
+    [setActivatorNodeRef, syncDraggableNodeRef],
+  );
+  const dispatchToolbarDragActivity = useCallback(
+    (active: boolean) => {
+      const ownerDocument = dragHandlerRef.current?.ownerDocument;
+      if (!ownerDocument) {
+        return;
+      }
+
+      ownerDocument.dispatchEvent(
+        new CustomEvent(TOOLBAR_DRAG_ACTIVITY_EVENT, {
+          detail: { active, modelUid: model.uid },
+        }),
+      );
+    },
+    [model.uid],
+  );
+
+  const dispatchToolbarDragAnchor = useCallback(
+    (detail: Pick<ToolbarDragAnchorDetail, 'point'>) => {
+      const ownerDocument = dragHandlerRef.current?.ownerDocument;
+      if (!ownerDocument) {
+        return;
+      }
+
+      ownerDocument.dispatchEvent(
+        new CustomEvent<ToolbarDragAnchorDetail>(TOOLBAR_DRAG_ANCHOR_EVENT, {
+          detail: { modelUid: model.uid, point: detail.point },
+        }),
+      );
+    },
+    [model.uid],
+  );
+
+  const clearPointerPressListeners = useCallback(() => {
+    pointerPressCleanupRef.current?.();
+    pointerPressCleanupRef.current = null;
+  }, []);
+
+  const syncToolbarDragActivity = useCallback(() => {
+    const nextActive = isPointerPressActiveRef.current || isDraggingRef.current;
+    if (nextActive === isToolbarDragActiveRef.current) {
+      return;
+    }
+
+    isToolbarDragActiveRef.current = nextActive;
+    dispatchToolbarDragActivity(nextActive);
+  }, [dispatchToolbarDragActivity]);
+
+  const handlePointerPressEnd = useCallback(() => {
+    isPointerPressActiveRef.current = false;
+    clearPointerPressListeners();
+    syncToolbarDragActivity();
+  }, [clearPointerPressListeners, syncToolbarDragActivity]);
+
+  const registerPointerPressListeners = useCallback(() => {
+    const ownerDocument = dragHandlerRef.current?.ownerDocument;
+    const ownerWindow = ownerDocument?.defaultView;
+    if (!ownerDocument) {
+      return;
+    }
+
+    clearPointerPressListeners();
+
+    const handlePointerEnd = () => {
+      handlePointerPressEnd();
+    };
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        handlePointerPressEnd();
+      }
+    };
+
+    ownerDocument.addEventListener('pointerup', handlePointerEnd, true);
+    ownerDocument.addEventListener('pointercancel', handlePointerEnd, true);
+    ownerDocument.addEventListener('keydown', handleKeyDown, true);
+    ownerWindow?.addEventListener('blur', handlePointerEnd);
+
+    pointerPressCleanupRef.current = () => {
+      ownerDocument.removeEventListener('pointerup', handlePointerEnd, true);
+      ownerDocument.removeEventListener('pointercancel', handlePointerEnd, true);
+      ownerDocument.removeEventListener('keydown', handleKeyDown, true);
+      ownerWindow?.removeEventListener('blur', handlePointerEnd);
+    };
+  }, [clearPointerPressListeners, handlePointerPressEnd]);
+
+  useEffect(() => {
+    syncDraggableNodeRef(dragHandlerRef.current);
+  }, [syncDraggableNodeRef]);
+
+  useEffect(() => {
+    isDraggingRef.current = isDragging;
+    syncToolbarDragActivity();
+  }, [isDragging, syncToolbarDragActivity]);
+
+  useEffect(() => {
+    return () => {
+      if (isToolbarDragActiveRef.current) {
+        dispatchToolbarDragActivity(false);
+      }
+      isPointerPressActiveRef.current = false;
+      isDraggingRef.current = false;
+      isToolbarDragActiveRef.current = false;
+      clearPointerPressListeners();
+    };
+  }, [clearPointerPressListeners, dispatchToolbarDragActivity]);
+
   return (
     <span
-      ref={setNodeRef}
+      ref={setDragHandlerNodeRef}
       {...listeners}
       {...attributes}
+      onPointerDownCapture={(event) => {
+        if (event.button !== 0) {
+          return;
+        }
+
+        dispatchToolbarDragAnchor({
+          point: {
+            x: event.clientX,
+            y: event.clientY,
+          },
+        });
+        isPointerPressActiveRef.current = true;
+        syncToolbarDragActivity();
+        registerPointerPressListeners();
+      }}
       style={{
         cursor: 'grab',
       }}
@@ -70,23 +283,73 @@ export const Droppable: FC<{ model: FlowModel<any>; children: React.ReactNode }>
   );
 };
 
+export interface DndProviderProps extends DndContextProps, PersistOptions {
+  /**
+   * Whether to render the built-in `DragOverlay` (the "Dragging" pill that
+   * follows the cursor). Defaults to `true` for backwards compatibility with
+   * existing flow-engine drag interactions. Set to `false` when the
+   * surrounding UI already gives clear visual feedback (e.g. a drag-sort
+   * table that highlights the drop position) and the floating pill would be
+   * redundant.
+   */
+  showDragOverlay?: boolean;
+}
+
 // 提供一个封装了 DragOverlay 的 DndProvider 组件，继承 DndContext 的所有 props
-export const DndProvider: FC<DndContextProps & PersistOptions> = ({
+export const DndProvider: FC<DndProviderProps> = ({
   persist = true,
+  showDragOverlay = true,
   children,
+  onDragStart,
   onDragEnd,
+  onDragCancel,
   ...restProps
 }) => {
   const [activeId, setActiveId] = useState<string | null>(null);
+  const [dragAnchorPoint, setDragAnchorPoint] = useState<ToolbarDragAnchorDetail['point']>(null);
   const flowEngine = useFlowEngine();
+
+  useEffect(() => {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const handleToolbarDragAnchor = (event: Event) => {
+      const customEvent = event as CustomEvent<ToolbarDragAnchorDetail>;
+      setDragAnchorPoint(customEvent.detail?.point || null);
+    };
+
+    document.addEventListener(TOOLBAR_DRAG_ANCHOR_EVENT, handleToolbarDragAnchor as EventListener);
+    return () => {
+      document.removeEventListener(TOOLBAR_DRAG_ANCHOR_EVENT, handleToolbarDragAnchor as EventListener);
+    };
+  }, []);
+
+  const overlayAnchorModifier = useCallback<Modifier>(
+    ({ active, activeNodeRect, transform }) => {
+      const nextTransform: Transform = resolveOverlayAnchorTransform({
+        activeId,
+        active,
+        transform,
+        activeNodeRect,
+        dragAnchorPoint,
+      });
+
+      return nextTransform;
+    },
+    [activeId, dragAnchorPoint],
+  );
+
   return (
     <DndContext
+      {...restProps}
       onDragStart={(event) => {
         setActiveId(event.active.id as string);
-        restProps.onDragStart?.(event);
+        onDragStart?.(event);
       }}
       onDragEnd={(event) => {
         setActiveId(null);
+        setDragAnchorPoint(null);
         // 如果没有 onDragEnd 回调，则默认调用 flowEngine 的 moveModel 方法
         if (!onDragEnd) {
           if (event.over) {
@@ -97,32 +360,46 @@ export const DndProvider: FC<DndContextProps & PersistOptions> = ({
           onDragEnd(event);
         }
       }}
+      onDragCancel={(event) => {
+        setActiveId(null);
+        setDragAnchorPoint(null);
+        onDragCancel?.(event);
+      }}
       {...restProps}
     >
       {children}
-      {createPortal(
-        <DragOverlay dropAnimation={null} zIndex={2000}>
-          {activeId && (
-            <span
-              style={{
-                display: 'inline-flex',
-                alignItems: 'center',
-                whiteSpace: 'nowrap',
-                background: '#fff',
-                border: '1px solid #1890ff',
-                borderRadius: 4,
-                padding: '4px 12px',
-                color: '#1890ff',
-                // fontSize: 18,
-                boxShadow: '0 2px 8px rgba(0,0,0,0.15)',
-              }}
+      {showDragOverlay && typeof document !== 'undefined'
+        ? createPortal(
+            <DragOverlay
+              dropAnimation={null}
+              modifiers={[overlayAnchorModifier]}
+              zIndex={2000}
+              style={{ pointerEvents: 'none' }}
             >
-              {flowEngine.translate('Dragging')}
-            </span>
-          )}
-        </DragOverlay>,
-        document.body,
-      )}
+              {activeId && (
+                <span
+                  data-testid="flow-drag-preview"
+                  style={{
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    whiteSpace: 'nowrap',
+                    background: '#fff',
+                    border: '1px solid #1890ff',
+                    borderRadius: 4,
+                    padding: '4px 12px',
+                    color: '#1890ff',
+                    pointerEvents: 'none',
+                    // fontSize: 18,
+                    boxShadow: '0 2px 8px rgba(0,0,0,0.15)',
+                  }}
+                >
+                  {flowEngine.translate('Dragging')}
+                </span>
+              )}
+            </DragOverlay>,
+            document.body,
+          )
+        : null}
     </DndContext>
   );
 };

package/src/components/settings/wrappers/component/SelectWithTitle.tsx

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { Select } from 'antd';
+import { Select, Tooltip } from 'antd';
 import React, { useEffect, useRef, useState } from 'react';
 import { useFlowEngineContext } from '../../../../provider';
 
@@ -19,6 +19,7 @@ export interface SelectWithTitleProps {
   itemKey?: string;
   onChange?: (...args: any[]) => void;
   dropdownRender?: any;
+  tooltip?: any;
 }
 
 export function SelectWithTitle({
@@ -28,6 +29,7 @@ export function SelectWithTitle({
   options,
   fieldNames,
   itemKey,
+  tooltip,
   ...others
 }: SelectWithTitleProps) {
   const [open, setOpen] = useState(false);
@@ -66,6 +68,17 @@ export function SelectWithTitle({
     setValue(val);
     onChange?.({ [itemKey]: val });
   };
+  const titleNode = (
+    <span
+      style={{
+        whiteSpace: 'nowrap', // 不换行
+        flexShrink: 0, // 不被挤压
+      }}
+    >
+      {title}
+    </span>
+  );
+
   return (
     <div
       style={{ alignItems: 'center', display: 'flex', justifyContent: 'space-between' }}
@@ -79,14 +92,13 @@ export function SelectWithTitle({
         }, 200);
       }}
     >
-      <span
-        style={{
-          whiteSpace: 'nowrap', // 不换行
-          flexShrink: 0, // 不被挤压
-        }}
-      >
-        {title}
-      </span>
+      {tooltip ? (
+        <Tooltip title={tooltip} placement="top" destroyTooltipOnHide>
+          {titleNode}
+        </Tooltip>
+      ) : (
+        titleNode
+      )}
       <Select
         {...others}
         open={open}

package/src/components/settings/wrappers/contextual/DefaultSettingsIcon.tsx

@@ -8,6 +8,7 @@
  */
 
 import { ExclamationCircleOutlined, MenuOutlined, QuestionCircleOutlined } from '@ant-design/icons';
+import { css } from '@emotion/css';
 import type { DropdownProps, MenuProps } from 'antd';
 import { App, Dropdown, Modal, Tooltip, theme } from 'antd';
 import React, { startTransition, useCallback, useEffect, useMemo, useState, FC } from 'react';
@@ -26,6 +27,26 @@ import { useNiceDropdownMaxHeight } from '../../../../hooks';
 import { SwitchWithTitle } from '../component/SwitchWithTitle';
 import { SelectWithTitle } from '../component/SelectWithTitle';
 import type { FlowSettingsContext } from '../../../../flowContext';
+
+const findExtraMenuItemByKey = (
+  items: FlowModelExtraMenuItem[],
+  targetKey: string,
+): FlowModelExtraMenuItem | undefined => {
+  for (const item of items) {
+    const itemKey = String(item?.key ?? '');
+    if (itemKey === targetKey) {
+      return item;
+    }
+    if (item.children?.length) {
+      const matched = findExtraMenuItemByKey(item.children, targetKey);
+      if (matched) {
+        return matched;
+      }
+    }
+  }
+  return undefined;
+};
+
 // Type definitions for better type safety
 interface StepInfo {
   stepKey: string;
@@ -188,15 +209,51 @@ interface DefaultSettingsIconProps {
   showCopyUidButton?: boolean;
   menuLevels?: number; // Menu levels: 1=current model only (default), 2=include sub-models
   flattenSubMenus?: boolean; // Whether to flatten sub-menus: false=group by model (default), true=flatten all
+  onDropdownVisibleChange?: (open: boolean) => void;
+  getPopupContainer?: DropdownProps['getPopupContainer'];
   [key: string]: any; // Allow additional props
 }
 
+const TOOLBAR_ICONS_SELECTOR = '.nb-toolbar-container-icons';
+const TOOLBAR_CONTAINER_SELECTOR = '.nb-toolbar-container';
+const TOOLBAR_DROPDOWN_OVERLAY_CLASS = css`
+  width: max-content;
+  min-width: max-content;
+
+  .ant-dropdown-menu {
+    width: max-content;
+    min-width: max-content;
+  }
+`;
+
+const getToolbarPopupContainer = (triggerNode?: HTMLElement | null) => {
+  if (!triggerNode) {
+    return null;
+  }
+
+  return (
+    (triggerNode.closest(TOOLBAR_ICONS_SELECTOR) as HTMLElement | null) ||
+    (triggerNode.closest(TOOLBAR_CONTAINER_SELECTOR) as HTMLElement | null)
+  );
+};
+
+const removeExtraMenuItemClickHandlers = (item: FlowModelExtraMenuItem): FlowModelExtraMenuItem => {
+  const { onClick: _onClick, children, ...rest } = item;
+
+  return {
+    ...rest,
+    children: children?.length ? children.map(removeExtraMenuItemClickHandlers) : undefined,
+  };
+};
+
 export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
   model,
   showDeleteButton = true,
   showCopyUidButton = true,
   menuLevels = 1, // 默认一级菜单
   flattenSubMenus = true,
+  onDropdownVisibleChange,
+  getPopupContainer,
 }) => {
   const { message } = App.useApp();
   const t = useMemo(() => getT(model), [model]);
@@ -210,15 +267,38 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
   const [isLoading, setIsLoading] = useState(true);
   const closeDropdown = useCallback(() => {
     setVisible(false);
-  }, []);
-  const handleOpenChange: DropdownProps['onOpenChange'] = useCallback((nextOpen: boolean, info) => {
-    if (info.source === 'trigger' || nextOpen) {
-      // 当鼠标快速滑过时，终止菜单的渲染，防止卡顿
-      startTransition(() => {
-        setVisible(nextOpen);
-      });
-    }
-  }, []);
+    onDropdownVisibleChange?.(false);
+  }, [onDropdownVisibleChange]);
+  const resolvePopupContainer = useCallback<NonNullable<DropdownProps['getPopupContainer']>>(
+    (triggerNode) => {
+      // 工具栏自身容器必须优先，保证鼠标从 icon 移到菜单时仍处于同一 hover 树。
+      // 弹窗场景的裁剪问题由 useFloatToolbarPortal 负责把 toolbar 挂到正确的 popup host。
+      return (
+        getToolbarPopupContainer(triggerNode) ||
+        getPopupContainer?.(triggerNode) ||
+        triggerNode?.parentElement ||
+        document.body
+      );
+    },
+    [getPopupContainer],
+  );
+  const handleOpenChange: DropdownProps['onOpenChange'] = useCallback(
+    (nextOpen: boolean, info) => {
+      if (info.source === 'trigger' || nextOpen) {
+        // 当鼠标快速滑过时，终止菜单的渲染，防止卡顿
+        startTransition(() => {
+          setVisible(nextOpen);
+        });
+        onDropdownVisibleChange?.(nextOpen);
+      }
+    },
+    [onDropdownVisibleChange],
+  );
+  useEffect(() => {
+    return () => {
+      onDropdownVisibleChange?.(false);
+    };
+  }, [onDropdownVisibleChange]);
   const dropdownMaxHeight = useNiceDropdownMaxHeight([visible]);
   useEffect(() => {
     let mounted = true;
@@ -422,7 +502,11 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
         return;
       }
 
-      const extra = extraMenuItems.find((it) => it?.key === originalKey || it?.key === cleanKey);
+      const extra =
+        findExtraMenuItemByKey(extraMenuItems, originalKey) || findExtraMenuItemByKey(extraMenuItems, cleanKey);
+      if (extra?.disabled) {
+        return;
+      }
       if (extra?.onClick) {
         closeDropdown();
         extra.onClick();
@@ -795,7 +879,8 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
       // });
 
       if (commonExtras.length > 0) {
-        items.push(...(commonExtras as MenuProps['items']));
+        // Antd Menu 会同时触发 item.onClick 和 menu.onClick，这里统一交给 handleMenuClick 执行。
+        items.push(...(commonExtras.map(removeExtraMenuItemClickHandlers) as MenuProps['items']));
       }
 
       // 添加复制uid按钮
@@ -833,6 +918,9 @@ export const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps> = ({
 
   return (
     <Dropdown
+      getPopupContainer={resolvePopupContainer}
+      overlayClassName={TOOLBAR_DROPDOWN_OVERLAY_CLASS}
+      overlayStyle={{ width: 'max-content', minWidth: 'max-content' }}
       onOpenChange={handleOpenChange}
       open={visible}
       menu={{