@nocobase/flow-engine 2.1.0-alpha.13 → 2.1.0-alpha.15

package/src/components/settings/wrappers/contextual/useFloatToolbarPortal.ts

@@ -0,0 +1,358 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { CSSProperties, RefObject } from 'react';
+
+const APP_CONTAINER_SELECTOR = '#nocobase-app-container';
+const DRAWER_CONTENT_WRAPPER_SELECTOR = '.ant-drawer-content-wrapper';
+const DRAWER_CONTENT_SELECTOR = '.ant-drawer-content';
+const DRAWER_ROOT_SELECTOR = '.ant-drawer-root';
+const MODAL_SELECTOR = '.ant-modal';
+const MODAL_WRAP_SELECTOR = '.ant-modal-wrap';
+const MODAL_ROOT_SELECTOR = '.ant-modal-root';
+
+type ToolbarPortalPositioningMode = 'fixed' | 'absolute';
+
+interface ToolbarPortalHostConfig {
+  mountElement: HTMLElement;
+  positioningElement: HTMLElement;
+  positioningMode: ToolbarPortalPositioningMode;
+}
+
+export interface ToolbarPortalRenderSnapshot {
+  mountElement: HTMLElement;
+  positioningMode: ToolbarPortalPositioningMode;
+}
+
+export interface ToolbarPortalRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+interface ToolbarPortalInset {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+}
+
+interface UseFloatToolbarPortalOptions {
+  active: boolean;
+  containerRef: RefObject<HTMLDivElement>;
+  toolbarContainerRef: RefObject<HTMLDivElement>;
+  toolbarStyle?: CSSProperties;
+}
+
+interface UseFloatToolbarPortalResult {
+  portalRect: ToolbarPortalRect;
+  portalRenderSnapshot: ToolbarPortalRenderSnapshot | null;
+  getPopupContainer: (triggerNode?: HTMLElement) => HTMLElement;
+  updatePortalRect: () => void;
+  schedulePortalRectUpdate: () => void;
+}
+
+const defaultPortalRect: ToolbarPortalRect = {
+  top: 0,
+  left: 0,
+  width: 0,
+  height: 0,
+};
+
+const getClosestElement = (hostEl: HTMLElement | null, selector: string) =>
+  hostEl?.closest(selector) as HTMLElement | null;
+
+const createAbsolutePortalHostConfig = (element: HTMLElement): ToolbarPortalHostConfig => ({
+  mountElement: element,
+  positioningElement: element,
+  positioningMode: 'absolute',
+});
+
+const popupPortalHostResolvers: Array<(hostEl: HTMLElement | null) => HTMLElement | null> = [
+  (hostEl) => getClosestElement(hostEl, DRAWER_CONTENT_WRAPPER_SELECTOR),
+  (hostEl) => getClosestElement(hostEl, MODAL_WRAP_SELECTOR),
+  (hostEl) => getClosestElement(hostEl, MODAL_SELECTOR),
+  (hostEl) => {
+    const drawerContent = getClosestElement(hostEl, DRAWER_CONTENT_SELECTOR);
+    return drawerContent ? getClosestElement(drawerContent, DRAWER_CONTENT_WRAPPER_SELECTOR) || drawerContent : null;
+  },
+  (hostEl) => getClosestElement(hostEl, DRAWER_ROOT_SELECTOR),
+  (hostEl) => getClosestElement(hostEl, MODAL_ROOT_SELECTOR),
+];
+
+const getPopupPortalHostConfig = (hostEl: HTMLElement | null): ToolbarPortalHostConfig | null => {
+  for (const resolveHost of popupPortalHostResolvers) {
+    const popupHost = resolveHost(hostEl);
+    if (popupHost) {
+      return createAbsolutePortalHostConfig(popupHost);
+    }
+  }
+
+  return null;
+};
+
+const getToolbarPortalHostConfig = (hostEl: HTMLElement | null): ToolbarPortalHostConfig | null => {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+
+  const popupRootConfig = getPopupPortalHostConfig(hostEl);
+  if (popupRootConfig) {
+    return popupRootConfig;
+  }
+
+  const appContainer = document.querySelector(APP_CONTAINER_SELECTOR) as HTMLElement | null;
+  if (appContainer) {
+    return createAbsolutePortalHostConfig(appContainer);
+  }
+
+  return {
+    mountElement: document.body,
+    positioningElement: document.body,
+    positioningMode: 'fixed',
+  };
+};
+
+const parseToolbarInsetValue = (value: CSSProperties['top']) => {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const trimmedValue = value.trim();
+    if (/^-?\d+(\.\d+)?(px)?$/.test(trimmedValue)) {
+      return Number.parseFloat(trimmedValue);
+    }
+  }
+
+  return 0;
+};
+
+const resolveToolbarPortalInset = (toolbarStyle?: CSSProperties): ToolbarPortalInset => {
+  return {
+    top: parseToolbarInsetValue(toolbarStyle?.top),
+    left: parseToolbarInsetValue(toolbarStyle?.left),
+    right: parseToolbarInsetValue(toolbarStyle?.right),
+    bottom: parseToolbarInsetValue(toolbarStyle?.bottom),
+  };
+};
+
+const getAbsolutePositioningElement = (
+  toolbarEl: HTMLElement | null,
+  portalHostConfig: ToolbarPortalHostConfig | null,
+) => {
+  if (!portalHostConfig || portalHostConfig.positioningMode !== 'absolute') {
+    return portalHostConfig?.positioningElement || null;
+  }
+
+  const offsetParent = toolbarEl?.offsetParent;
+  if (
+    offsetParent instanceof HTMLElement &&
+    offsetParent !== document.body &&
+    offsetParent !== document.documentElement
+  ) {
+    return offsetParent;
+  }
+
+  return portalHostConfig.positioningElement;
+};
+
+const calculatePortalRect = (
+  hostEl: HTMLElement | null,
+  portalHostConfig: ToolbarPortalHostConfig | null,
+  toolbarStyle?: CSSProperties,
+  toolbarEl?: HTMLElement | null,
+): ToolbarPortalRect => {
+  if (!hostEl) {
+    return defaultPortalRect;
+  }
+
+  const inset = resolveToolbarPortalInset(toolbarStyle);
+  const hostRect = hostEl.getBoundingClientRect();
+
+  let rect: ToolbarPortalRect;
+  if (!portalHostConfig || portalHostConfig.positioningMode === 'fixed') {
+    rect = {
+      top: hostRect.top,
+      left: hostRect.left,
+      width: hostRect.width,
+      height: hostRect.height,
+    };
+  } else {
+    const positioningElement = getAbsolutePositioningElement(toolbarEl || null, portalHostConfig);
+    const portalHostRect =
+      positioningElement?.getBoundingClientRect() || portalHostConfig.positioningElement.getBoundingClientRect();
+    const scrollTop = positioningElement?.scrollTop ?? portalHostConfig.positioningElement.scrollTop;
+    const scrollLeft = positioningElement?.scrollLeft ?? portalHostConfig.positioningElement.scrollLeft;
+
+    rect = {
+      top: hostRect.top - portalHostRect.top + scrollTop,
+      left: hostRect.left - portalHostRect.left + scrollLeft,
+      width: hostRect.width,
+      height: hostRect.height,
+    };
+  }
+
+  return {
+    top: rect.top + inset.top,
+    left: rect.left + inset.left,
+    width: Math.max(0, rect.width - inset.left - inset.right),
+    height: Math.max(0, rect.height - inset.top - inset.bottom),
+  };
+};
+
+export const omitToolbarPortalInsetStyle = (toolbarStyle?: CSSProperties): CSSProperties | undefined => {
+  if (!toolbarStyle) {
+    return undefined;
+  }
+
+  const nextStyle = { ...toolbarStyle };
+  delete nextStyle.top;
+  delete nextStyle.left;
+  delete nextStyle.right;
+  delete nextStyle.bottom;
+  return nextStyle;
+};
+
+export const useFloatToolbarPortal = ({
+  active,
+  containerRef,
+  toolbarContainerRef,
+  toolbarStyle,
+}: UseFloatToolbarPortalOptions): UseFloatToolbarPortalResult => {
+  const [portalRect, setPortalRect] = useState<ToolbarPortalRect>(defaultPortalRect);
+  const [portalRenderSnapshot, setPortalRenderSnapshot] = useState<ToolbarPortalRenderSnapshot | null>(null);
+  const portalHostConfigRef = useRef<ToolbarPortalHostConfig | null>(null);
+  const portalRafIdRef = useRef<number | null>(null);
+
+  const updatePortalRect = useCallback(() => {
+    const hostElement = containerRef.current;
+    if (!hostElement) {
+      return;
+    }
+
+    const nextPortalHostConfig = getToolbarPortalHostConfig(hostElement);
+    portalHostConfigRef.current = nextPortalHostConfig;
+    setPortalRenderSnapshot((prevSnapshot) => {
+      if (!nextPortalHostConfig) {
+        return prevSnapshot === null ? prevSnapshot : null;
+      }
+
+      if (
+        prevSnapshot?.mountElement === nextPortalHostConfig.mountElement &&
+        prevSnapshot?.positioningMode === nextPortalHostConfig.positioningMode
+      ) {
+        return prevSnapshot;
+      }
+
+      return {
+        mountElement: nextPortalHostConfig.mountElement,
+        positioningMode: nextPortalHostConfig.positioningMode,
+      };
+    });
+
+    const nextRect = calculatePortalRect(hostElement, nextPortalHostConfig, toolbarStyle, toolbarContainerRef.current);
+    setPortalRect((prevRect) => {
+      if (
+        prevRect.top === nextRect.top &&
+        prevRect.left === nextRect.left &&
+        prevRect.width === nextRect.width &&
+        prevRect.height === nextRect.height
+      ) {
+        return prevRect;
+      }
+      return nextRect;
+    });
+  }, [containerRef, toolbarContainerRef, toolbarStyle]);
+
+  const schedulePortalRectUpdate = useCallback(() => {
+    if (portalRafIdRef.current !== null) {
+      return;
+    }
+
+    portalRafIdRef.current = window.requestAnimationFrame(() => {
+      portalRafIdRef.current = null;
+      updatePortalRect();
+    });
+  }, [updatePortalRect]);
+
+  const getPopupContainer = useCallback(
+    (triggerNode?: HTMLElement) => {
+      const fallbackContainer =
+        triggerNode?.ownerDocument?.body ||
+        containerRef.current?.ownerDocument?.body ||
+        (typeof document !== 'undefined' ? document.body : null);
+
+      return (portalHostConfigRef.current?.mountElement ||
+        getToolbarPortalHostConfig(triggerNode || containerRef.current)?.mountElement ||
+        fallbackContainer) as HTMLElement;
+    },
+    [containerRef],
+  );
+
+  useEffect(() => {
+    if (!active) {
+      return;
+    }
+
+    updatePortalRect();
+
+    const handleViewportChange = () => {
+      schedulePortalRectUpdate();
+    };
+
+    const container = containerRef.current;
+    const mountElement = portalHostConfigRef.current?.mountElement;
+    const positioningElement = portalHostConfigRef.current?.positioningElement;
+    const resizeObserver =
+      typeof ResizeObserver !== 'undefined' && container
+        ? new ResizeObserver(() => {
+            schedulePortalRectUpdate();
+          })
+        : null;
+
+    if (container) {
+      resizeObserver?.observe(container);
+    }
+    if (mountElement && mountElement !== container) {
+      resizeObserver?.observe(mountElement);
+    }
+    if (positioningElement && positioningElement !== container && positioningElement !== mountElement) {
+      resizeObserver?.observe(positioningElement);
+    }
+
+    window.addEventListener('resize', handleViewportChange);
+    window.addEventListener('scroll', handleViewportChange, true);
+
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener('resize', handleViewportChange);
+      window.removeEventListener('scroll', handleViewportChange, true);
+    };
+  }, [active, containerRef, schedulePortalRectUpdate, updatePortalRect]);
+
+  useEffect(() => {
+    return () => {
+      if (portalRafIdRef.current !== null) {
+        window.cancelAnimationFrame(portalRafIdRef.current);
+      }
+      portalHostConfigRef.current = null;
+    };
+  }, []);
+
+  return {
+    portalRect,
+    portalRenderSnapshot,
+    getPopupContainer,
+    updatePortalRect,
+    schedulePortalRectUpdate,
+  };
+};

package/src/components/settings/wrappers/contextual/useFloatToolbarVisibility.ts

@@ -0,0 +1,281 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { MouseEvent as ReactMouseEvent, RefObject } from 'react';
+
+const TOOLBAR_HIDE_DELAY = 180;
+const CHILD_FLOAT_MENU_ACTIVITY_EVENT = 'nb-float-menu-child-activity';
+
+interface UseFloatToolbarVisibilityOptions {
+  modelUid: string;
+  containerRef: RefObject<HTMLDivElement>;
+  toolbarContainerRef: RefObject<HTMLDivElement>;
+  updatePortalRect: () => void;
+  schedulePortalRectUpdate: () => void;
+}
+
+interface UseFloatToolbarVisibilityResult {
+  isToolbarVisible: boolean;
+  shouldRenderToolbar: boolean;
+  handleSettingsMenuOpenChange: (open: boolean) => void;
+  handleChildHover: (e: ReactMouseEvent) => void;
+  handleHostMouseEnter: () => void;
+  handleHostMouseLeave: (e: ReactMouseEvent<HTMLDivElement>) => void;
+  handleToolbarMouseEnter: () => void;
+  handleToolbarMouseLeave: (e: ReactMouseEvent<HTMLDivElement>) => void;
+  handleResizeDragStart: () => void;
+  handleResizeDragEnd: () => void;
+}
+
+const isNodeWithin = (target: EventTarget | null, container: HTMLElement | null): boolean => {
+  return target instanceof Node && !!container?.contains(target);
+};
+
+const getToolbarModelUidFromTarget = (target: EventTarget | null): string | null => {
+  if (!(target instanceof Element)) {
+    return null;
+  }
+
+  return target.closest('.nb-toolbar-container[data-model-uid]')?.getAttribute('data-model-uid') || null;
+};
+
+const isNodeWithinDescendantFloatToolbar = (
+  target: EventTarget | null,
+  container: HTMLElement | null,
+  currentModelUid: string,
+): boolean => {
+  const targetModelUid = getToolbarModelUidFromTarget(target);
+  if (!container || !targetModelUid || targetModelUid === currentModelUid) {
+    return false;
+  }
+
+  return Array.from(
+    container.querySelectorAll<HTMLElement>('[data-has-float-menu="true"][data-float-menu-model-uid]'),
+  ).some(
+    (hostElement) =>
+      hostElement !== container && hostElement.getAttribute('data-float-menu-model-uid') === targetModelUid,
+  );
+};
+
+export const useFloatToolbarVisibility = ({
+  modelUid,
+  containerRef,
+  toolbarContainerRef,
+  updatePortalRect,
+  schedulePortalRectUpdate,
+}: UseFloatToolbarVisibilityOptions): UseFloatToolbarVisibilityResult => {
+  const [hideMenu, setHideMenu] = useState(false);
+  const [isHostHovered, setIsHostHovered] = useState(false);
+  const [isToolbarHovered, setIsToolbarHovered] = useState(false);
+  const [isDraggingToolbar, setIsDraggingToolbar] = useState(false);
+  const [isToolbarPinned, setIsToolbarPinned] = useState(false);
+  const [isHidePending, setIsHidePending] = useState(false);
+  const [activeChildToolbarIds, setActiveChildToolbarIds] = useState<string[]>([]);
+  const hideToolbarTimerRef = useRef<number | null>(null);
+  const reportedChildActivityToAncestorsRef = useRef(false);
+
+  const hasActiveChildToolbar = activeChildToolbarIds.length > 0;
+  const isToolbarVisible =
+    !hideMenu && !hasActiveChildToolbar && (isHostHovered || isToolbarHovered || isDraggingToolbar || isToolbarPinned);
+  const shouldRenderToolbar = isToolbarVisible || isToolbarPinned || isDraggingToolbar;
+  const isToolbarInteractionActive =
+    isHostHovered || isToolbarHovered || isDraggingToolbar || isToolbarPinned || isHidePending;
+
+  const clearHideToolbarTimer = useCallback(() => {
+    if (hideToolbarTimerRef.current !== null) {
+      window.clearTimeout(hideToolbarTimerRef.current);
+      hideToolbarTimerRef.current = null;
+    }
+    setIsHidePending(false);
+  }, []);
+
+  const scheduleHideToolbar = useCallback(() => {
+    clearHideToolbarTimer();
+    setIsHidePending(true);
+    hideToolbarTimerRef.current = window.setTimeout(() => {
+      hideToolbarTimerRef.current = null;
+      setIsHidePending(false);
+      if (isDraggingToolbar || isToolbarPinned) {
+        return;
+      }
+      setIsHostHovered(false);
+      setIsToolbarHovered(false);
+    }, TOOLBAR_HIDE_DELAY);
+  }, [clearHideToolbarTimer, isDraggingToolbar, isToolbarPinned]);
+
+  const handleSettingsMenuOpenChange = useCallback((open: boolean) => {
+    setIsToolbarPinned(open);
+  }, []);
+
+  useEffect(() => {
+    const hostElement = containerRef.current;
+    if (!hostElement) {
+      return;
+    }
+
+    const handleChildToolbarActivity = (event: Event) => {
+      const customEvent = event as CustomEvent<{ active?: boolean; modelUid?: string }>;
+      if (!(customEvent.target instanceof HTMLElement) || customEvent.target === hostElement) {
+        return;
+      }
+
+      const childModelUid = customEvent.detail?.modelUid;
+      if (!childModelUid) {
+        return;
+      }
+
+      setActiveChildToolbarIds((prevIds) => {
+        return customEvent.detail?.active
+          ? prevIds.includes(childModelUid)
+            ? prevIds
+            : [...prevIds, childModelUid]
+          : prevIds.filter((id) => id !== childModelUid);
+      });
+    };
+
+    hostElement.addEventListener(CHILD_FLOAT_MENU_ACTIVITY_EVENT, handleChildToolbarActivity as EventListener);
+    return () => {
+      hostElement.removeEventListener(CHILD_FLOAT_MENU_ACTIVITY_EVENT, handleChildToolbarActivity as EventListener);
+    };
+  }, [containerRef]);
+
+  useEffect(() => {
+    const hostElement = containerRef.current;
+    if (!hostElement || reportedChildActivityToAncestorsRef.current === isToolbarInteractionActive) {
+      return;
+    }
+
+    reportedChildActivityToAncestorsRef.current = isToolbarInteractionActive;
+    hostElement.dispatchEvent(
+      new CustomEvent(CHILD_FLOAT_MENU_ACTIVITY_EVENT, {
+        bubbles: true,
+        detail: { active: isToolbarInteractionActive, modelUid },
+      }),
+    );
+  }, [containerRef, isToolbarInteractionActive, modelUid]);
+
+  useEffect(() => {
+    const hostElement = containerRef.current;
+
+    return () => {
+      if (hostElement && reportedChildActivityToAncestorsRef.current) {
+        hostElement.dispatchEvent(
+          new CustomEvent(CHILD_FLOAT_MENU_ACTIVITY_EVENT, {
+            bubbles: true,
+            detail: { active: false, modelUid },
+          }),
+        );
+        reportedChildActivityToAncestorsRef.current = false;
+      }
+      clearHideToolbarTimer();
+    };
+  }, [clearHideToolbarTimer, containerRef, modelUid]);
+
+  useEffect(() => {
+    if (isToolbarPinned) {
+      clearHideToolbarTimer();
+      updatePortalRect();
+    }
+  }, [clearHideToolbarTimer, isToolbarPinned, updatePortalRect]);
+
+  const handleChildHover = useCallback(
+    (e: ReactMouseEvent) => {
+      const target = e.target as HTMLElement;
+      const childWithMenu = target.closest('[data-has-float-menu]');
+      const isCurrentHostTarget = !childWithMenu || childWithMenu === containerRef.current;
+
+      if (isCurrentHostTarget) {
+        clearHideToolbarTimer();
+        setIsHostHovered(true);
+      }
+
+      setHideMenu(!!childWithMenu && childWithMenu !== containerRef.current);
+    },
+    [clearHideToolbarTimer, containerRef],
+  );
+
+  const handleHostMouseEnter = useCallback(() => {
+    clearHideToolbarTimer();
+    setHideMenu(false);
+    updatePortalRect();
+    setIsHostHovered(true);
+  }, [clearHideToolbarTimer, updatePortalRect]);
+
+  const handleHostMouseLeave = useCallback(
+    (e: ReactMouseEvent<HTMLDivElement>) => {
+      if (isToolbarPinned) {
+        setIsHostHovered(false);
+        return;
+      }
+      if (isNodeWithin(e.relatedTarget, toolbarContainerRef.current)) {
+        clearHideToolbarTimer();
+        setIsHostHovered(false);
+        setIsToolbarHovered(true);
+        return;
+      }
+      if (isNodeWithinDescendantFloatToolbar(e.relatedTarget, containerRef.current, modelUid)) {
+        clearHideToolbarTimer();
+        setHideMenu(false);
+        setIsHostHovered(true);
+        return;
+      }
+      scheduleHideToolbar();
+    },
+    [clearHideToolbarTimer, containerRef, isToolbarPinned, modelUid, scheduleHideToolbar, toolbarContainerRef],
+  );
+
+  const handleToolbarMouseEnter = useCallback(() => {
+    clearHideToolbarTimer();
+    updatePortalRect();
+    setIsHostHovered(false);
+    setIsToolbarHovered(true);
+  }, [clearHideToolbarTimer, updatePortalRect]);
+
+  const handleToolbarMouseLeave = useCallback(
+    (e: ReactMouseEvent<HTMLDivElement>) => {
+      if (isToolbarPinned) {
+        setIsToolbarHovered(false);
+        return;
+      }
+      setIsToolbarHovered(false);
+      if (isNodeWithin(e.relatedTarget, containerRef.current)) {
+        clearHideToolbarTimer();
+        setIsHostHovered(true);
+        return;
+      }
+      scheduleHideToolbar();
+    },
+    [clearHideToolbarTimer, containerRef, isToolbarPinned, scheduleHideToolbar],
+  );
+
+  const handleResizeDragStart = useCallback(() => {
+    updatePortalRect();
+    setIsDraggingToolbar(true);
+    schedulePortalRectUpdate();
+  }, [schedulePortalRectUpdate, updatePortalRect]);
+
+  const handleResizeDragEnd = useCallback(() => {
+    setIsDraggingToolbar(false);
+    schedulePortalRectUpdate();
+  }, [schedulePortalRectUpdate]);
+
+  return {
+    isToolbarVisible,
+    shouldRenderToolbar,
+    handleSettingsMenuOpenChange,
+    handleChildHover,
+    handleHostMouseEnter,
+    handleHostMouseLeave,
+    handleToolbarMouseEnter,
+    handleToolbarMouseLeave,
+    handleResizeDragStart,
+    handleResizeDragEnd,
+  };
+};

package/src/components/subModel/__tests__/AddSubModelButton.test.tsx

@@ -1117,7 +1117,6 @@ describe('AddSubModelButton toggleable behavior', () => {
   // Minimal fake repository for save/destroy
   class FakeRepo implements IFlowModelRepository<any> {
     findOne = vi.fn().mockResolvedValue(null);
-    ensure = vi.fn(async (values: any) => await this.findOne(values));
     save = vi.fn().mockResolvedValue({});
     destroy = vi.fn().mockResolvedValue(true);
     move = vi.fn().mockResolvedValue(undefined);

package/src/data-source/index.ts

@@ -501,6 +501,12 @@ export class Collection {
 
   get titleCollectionField() {
     const titleFieldName = this.options.titleField || this.filterTargetKey;
+    if (Array.isArray(titleFieldName)) {
+      if (titleFieldName.length !== 1) {
+        return undefined;
+      }
+      return this.getField(titleFieldName[0]);
+    }
     const titleCollectionField = this.getField(titleFieldName);
     return titleCollectionField;
   }

package/src/flowContext.ts

@@ -11,6 +11,7 @@ import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
 import { APIClient, RequestOptions } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
+import axios from 'axios';
 import { MessageInstance } from 'antd/es/message/interface';
 import * as antd from 'antd';
 import type { HookAPI } from 'antd/es/modal/useModal';
@@ -58,6 +59,31 @@ import dayjs from 'dayjs';
 import { externalReactRender, setupRunJSLibs } from './runjsLibs';
 import { runjsImportAsync, runjsImportModule, runjsRequireAsync } from './utils/runjsModuleLoader';
 
+function normalizePathname(pathname: string) {
+  return pathname.endsWith('/') ? pathname : `${pathname}/`;
+}
+
+function shouldBypassApiClient(url: string, app?: { getApiUrl?: (pathname?: string) => string }) {
+  try {
+    const requestUrl = new URL(url);
+    if (!['http:', 'https:'].includes(requestUrl.protocol)) {
+      return false;
+    }
+
+    if (!app?.getApiUrl) {
+      return true;
+    }
+
+    const apiUrl = new URL(app.getApiUrl());
+    const apiPath = normalizePathname(apiUrl.pathname);
+    const requestPath = normalizePathname(requestUrl.pathname);
+
+    return requestUrl.origin !== apiUrl.origin || !requestPath.startsWith(apiPath);
+  } catch {
+    return false;
+  }
+}
+
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
   return !!(val && typeof val === 'object' && 'collection' in val && 'filterByTk' in val);
@@ -3024,6 +3050,10 @@ class BaseFlowEngineContext extends FlowContext {
       return this.engine.getModel(modelName, searchInPreviousEngines);
     });
     this.defineMethod('request', (options: RequestOptions) => {
+      const app = this.app as { getApiUrl?: (pathname?: string) => string } | undefined;
+      if (typeof options?.url === 'string' && shouldBypassApiClient(options.url, app)) {
+        return axios.request(options);
+      }
       return this.api.request(options);
     });
     this.defineMethod(