@nocobase/flow-engine 2.1.0-alpha.2 → 2.1.0-alpha.20

package/src/__tests__/renderHiddenInConfig.test.tsx

@@ -14,7 +14,7 @@ import { FlowEngine } from '../flowEngine';
 import { FlowModel, ModelRenderMode } from '../models/flowModel';
 
 describe('FlowModel.renderHiddenInConfig', () => {
-  it('renders via renderHiddenInConfig when hidden and config enabled (React element mode, mounted)', () => {
+  it('renders via renderHiddenInConfig when hidden and config enabled (React element mode, mounted)', async () => {
     class ElemModel extends FlowModel {
       render() {
         return <div data-testid="content">Content</div>;
@@ -28,14 +28,14 @@ describe('FlowModel.renderHiddenInConfig', () => {
     const model = new ElemModel({ uid: 'elem-1', flowEngine: engine });
 
     // runtime hidden => mounted result should be empty (no content/hidden)
-    engine.flowSettings.disable();
+    await engine.flowSettings.disable();
     model.setHidden(true);
     const { container, unmount, rerender } = render(model.render() as React.ReactElement);
     expect(screen.queryByTestId('content')).toBeNull();
     expect(screen.queryByTestId('hidden')).toBeNull();
 
     // config enabled + hidden => should show renderHiddenInConfig result
-    engine.flowSettings.enable();
+    await engine.flowSettings.enable();
     rerender(model.render() as React.ReactElement);
     expect(screen.getByTestId('hidden').textContent).toBe('HiddenViaAPI');
 
@@ -46,7 +46,7 @@ describe('FlowModel.renderHiddenInConfig', () => {
     unmount();
     cleanup();
   });
-  it('returns a render function when hidden and config enabled (RenderFunction mode)', () => {
+  it('returns a render function when hidden and config enabled (RenderFunction mode)', async () => {
     class FuncModel extends FlowModel {
       static override renderMode = ModelRenderMode.RenderFunction;
       render() {
@@ -63,13 +63,13 @@ describe('FlowModel.renderHiddenInConfig', () => {
     const model = engine.createModel({ use: 'FuncModel' }) as FuncModel;
 
     // runtime hidden => null
-    engine.flowSettings.disable();
+    await engine.flowSettings.disable();
     model.setHidden(true);
     const runtimeHidden = model.render();
     expect(runtimeHidden).toBeNull();
 
     // config enabled + hidden => renderHiddenInConfig (function)
-    engine.flowSettings.enable();
+    await engine.flowSettings.enable();
     const cfgHidden = model.render();
     expect(typeof cfgHidden).toBe('function');
     const cellNode = (cfgHidden as any)();

package/src/__tests__/runjsContext.test.ts

@@ -29,11 +29,16 @@ describe('flowRunJSContext registry and doc', () => {
       expect(RunJSContextRegistry['resolve']('v1' as any, '*')).toBeTruthy();
     });
 
+    it('should register v2 mapping', () => {
+      expect(RunJSContextRegistry['resolve']('v2' as any, '*')).toBeTruthy();
+    });
+
     it('should register all context types', () => {
       const contextTypes = [
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',
@@ -44,12 +49,22 @@ describe('flowRunJSContext registry and doc', () => {
         const ctor = RunJSContextRegistry['resolve']('v1' as any, modelClass);
         expect(ctor).toBeTruthy();
       });
+
+      contextTypes.forEach((modelClass) => {
+        const ctor = RunJSContextRegistry['resolve']('v2' as any, modelClass);
+        expect(ctor).toBeTruthy();
+      });
     });
 
     it('should expose scene metadata for contexts', () => {
       expect(getRunJSScenesForModel('JSBlockModel', 'v1')).toEqual(['block']);
       expect(getRunJSScenesForModel('JSFieldModel', 'v1')).toEqual(['detail']);
+      expect(getRunJSScenesForModel('JSItemActionModel', 'v1')).toEqual(['table']);
+      expect(getRunJSScenesForModel('JSBlockModel', 'v2')).toEqual(['block']);
+      expect(getRunJSScenesForModel('JSFieldModel', 'v2')).toEqual(['detail']);
+      expect(getRunJSScenesForModel('JSItemActionModel', 'v2')).toEqual(['table']);
       expect(getRunJSScenesForModel('UnknownModel', 'v1')).toEqual([]);
+      expect(getRunJSScenesForModel('UnknownModel', 'v2')).toEqual([]);
     });
 
     it('should only execute once (idempotent)', async () => {
@@ -175,6 +190,7 @@ describe('flowRunJSContext registry and doc', () => {
       const ctx = new FlowContext();
       ctx.defineProperty('model', { value: { constructor: { name: 'JSColumnModel' } } });
       expect(getRunJSScenesForContext(ctx as any, { version: 'v1' })).toEqual(['table']);
+      expect(getRunJSScenesForContext(ctx as any, { version: 'v2' })).toEqual(['table']);
     });
 
     it('JSBlockModel context should have element property in doc', () => {

package/src/__tests__/runjsContextRuntime.test.ts

@@ -186,6 +186,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',
@@ -237,6 +238,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',

package/src/__tests__/runjsPreprocessDefault.test.ts

@@ -36,6 +36,29 @@ describe('ctx.runjs preprocessTemplates default', () => {
     expect(r.value).toBe('{{ctx.user.id}}');
   });
 
+  it('disables template preprocess by default for version v2', async () => {
+    const engine = new FlowEngine();
+    const ctx = engine.context as any;
+    ctx.defineProperty('user', { value: { id: 123 } });
+
+    const r = await ctx.runjs('return "{{ctx.user.id}}";', undefined, { version: 'v2' });
+    expect(r.success).toBe(true);
+    expect(r.value).toBe('{{ctx.user.id}}');
+  });
+
+  it('keeps explicit preprocessTemplates override higher priority than version', async () => {
+    const engine = new FlowEngine();
+    const ctx = engine.context as any;
+    ctx.defineProperty('user', { value: { id: 123 } });
+
+    const r = await ctx.runjs('return "{{ctx.user.id}}";', undefined, {
+      version: 'v2',
+      preprocessTemplates: true,
+    });
+    expect(r.success).toBe(true);
+    expect(r.value).toBe('123');
+  });
+
   it('does not double-preprocess already prepared code', async () => {
     const engine = new FlowEngine();
     const ctx = engine.context as any;

package/src/__tests__/runjsSnippets.test.ts

@@ -112,6 +112,27 @@ describe('RunJS Snippets', () => {
       expect(multiScene?.scenes).toEqual(expect.arrayContaining(['detail', 'table']));
       expect(multiScene?.groups).toEqual(expect.arrayContaining(['scene/detail', 'scene/table']));
     });
+
+    it('should expose new style snippets for matching contexts', async () => {
+      const tableSnippets = await listSnippetsForContext('JSColumnRunJSContext', 'v1', 'zh-CN');
+      const fieldSnippets = await listSnippetsForContext('FormJSFieldItemRunJSContext', 'v1', 'zh-CN');
+      const detailEventSnippets = await listSnippetsForContext('DetailsItemModel', 'v1', 'zh-CN');
+      const tableEventSnippets = await listSnippetsForContext('TableColumnModel', 'v1', 'zh-CN');
+
+      const tableStyle = tableSnippets.find((s) => s.ref === 'scene/table/set-cell-style');
+      expect(tableStyle?.name).toBe('表格字段样式设置');
+      expect(tableStyle?.body).toContain('ctx.model.props.onCell');
+      expect(tableStyle?.scenes).toEqual(['tableFieldEvent']);
+
+      const fieldStyle = fieldSnippets.find((s) => s.ref === 'scene/detail/set-field-style');
+      expect(fieldStyle?.name).toBe('设置表单项/详情项样式');
+      expect(fieldStyle?.body).toContain('ctx.model.props.style');
+      expect(fieldStyle?.scenes).toEqual(expect.arrayContaining(['detailFieldEvent', 'formFieldEvent']));
+      expect(fieldStyle?.groups).toEqual(expect.arrayContaining(['scene/detail', 'scene/form']));
+
+      expect(detailEventSnippets.some((s) => s.ref === 'scene/detail/set-field-style')).toBe(true);
+      expect(tableEventSnippets.some((s) => s.ref === 'scene/table/set-cell-style')).toBe(true);
+    });
   });
 
   describe('New snippets', () => {

package/src/__tests__/viewScopedFlowEngine.test.ts

@@ -256,11 +256,11 @@ describe('ViewScopedFlowEngine', () => {
 
     // Both children should return null from hydration because parent has flowSettingsEnabled
     // This is the bug fix: previously only children with their own flowSettingsEnabled would return null
-    const result1 = (scoped as any).hydrateModelFromPreviousEngines({
+    const result1 = await (scoped as any).hydrateModelFromPreviousEngines({
       parentId: 'parent-with-settings',
       subKey: 'popup',
     });
-    const result2 = (scoped as any).hydrateModelFromPreviousEngines({
+    const result2 = await (scoped as any).hydrateModelFromPreviousEngines({
       parentId: 'parent-with-settings',
       subKey: 'items',
     });
@@ -298,7 +298,7 @@ describe('ViewScopedFlowEngine', () => {
     const scoped = createViewScopedEngine(root);
 
     // Call the private method hydrateModelFromPreviousEngines directly
-    const result = (scoped as any).hydrateModelFromPreviousEngines({
+    const result = await (scoped as any).hydrateModelFromPreviousEngines({
       parentId: 'parent-normal',
       subKey: 'content',
     });

package/src/components/FlowModelRenderer.tsx

@@ -69,7 +69,7 @@ export interface FlowModelRendererProps {
         showBackground?: boolean;
         showBorder?: boolean;
         showDragHandle?: boolean;
-        /** 自定义工具栏样式 */
+        /** 自定义工具栏样式，`top/left/right/bottom` 会作为 portal overlay 的 inset 使用 */
         style?: React.CSSProperties;
         /**
          * @default 'inside'
@@ -112,6 +112,7 @@ const FlowModelRendererWithAutoFlows: React.FC<{
         showBackground?: boolean;
         showBorder?: boolean;
         showDragHandle?: boolean;
+        /** `top/left/right/bottom` 会作为 portal overlay 的 inset 使用 */
         style?: React.CSSProperties;
         /**
          * @default 'inside'
@@ -182,6 +183,7 @@ const FlowModelRendererCore: React.FC<{
         showBackground?: boolean;
         showBorder?: boolean;
         showDragHandle?: boolean;
+        /** `top/left/right/bottom` 会作为 portal overlay 的 inset 使用 */
         style?: React.CSSProperties;
         /**
          * @default 'inside'

package/src/components/MobilePopup.tsx

@@ -8,11 +8,13 @@
  */
 
 import { ConfigProvider } from 'antd';
-import { Popup } from 'antd-mobile';
 import React, { FC, ReactNode, useMemo } from 'react';
-import { CloseOutline } from 'antd-mobile-icons';
 import { useMobileActionDrawerStyle } from './MobilePopup.style';
 import { useTranslation } from 'react-i18next';
+import { lazy } from '../lazy-helper';
+
+const { Popup } = lazy(() => import('antd-mobile'), 'Popup');
+const { CloseOutline } = lazy(() => import('antd-mobile-icons'), 'CloseOutline');
 
 interface MobilePopupProps {
   title?: string;

package/src/components/__tests__/flow-model-render-error-fallback.test.tsx

@@ -9,7 +9,7 @@
 
 import React from 'react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, cleanup, waitFor } from '@testing-library/react';
+import { render, cleanup, fireEvent, waitFor } from '@testing-library/react';
 import { App, ConfigProvider } from 'antd';
 import { FlowEngine } from '../../flowEngine';
 import { FlowModel, ModelRenderMode } from '../../models/flowModel';
@@ -94,6 +94,16 @@ const clickDeleteFromLastDropdown = async () => {
   menu.onClick?.({ key: 'delete' });
 };
 
+const getHost = (element: HTMLElement) => element.closest('[data-has-float-menu="true"]') as HTMLDivElement;
+
+const hoverHostAndClickDelete = async (element: HTMLElement) => {
+  const host = getHost(element);
+  if (host) {
+    fireEvent.mouseEnter(host);
+  }
+  await clickDeleteFromLastDropdown();
+};
+
 // ---------------- Tests ----------------
 describe('Delete problematic model via FlowSettings menu', () => {
   beforeEach(() => {
@@ -114,13 +124,13 @@ describe('Delete problematic model via FlowSettings menu', () => {
     }
 
     const engine = new FlowEngine();
-    engine.flowSettings.forceEnable();
+    await engine.flowSettings.forceEnable();
     engine.registerModels({ BrokenModel });
     const model = engine.createModel({ use: 'BrokenModel', uid: 'broken-top-2' }) as BrokenModel;
     // satisfy FlowsFloatContextMenu styles
     model.context.defineProperty('themeToken', { value: { borderRadiusLG: 8 } });
 
-    render(
+    const { findByTestId } = render(
       <ConfigProvider>
         <App>
           <FlowEngineProvider engine={engine}>
@@ -130,7 +140,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
       </ConfigProvider>,
     );
 
-    await clickDeleteFromLastDropdown();
+    await hoverHostAndClickDelete(await findByTestId('result'));
     expect(engine.getModel(model.uid)).toBeUndefined();
   });
 
@@ -154,7 +164,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
     }
 
     const engine = new FlowEngine();
-    engine.flowSettings.forceEnable();
+    await engine.flowSettings.forceEnable();
     engine.registerModels({ ParentModel, BrokenChild });
     const parent = engine.createModel({ use: 'ParentModel', uid: 'parent-3' }) as ParentModel;
     const child = engine.createModel({ use: 'BrokenChild', uid: 'child-3' }) as BrokenChild;
@@ -163,7 +173,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
     parent.context.defineProperty('themeToken', { value: { borderRadiusLG: 8 } });
     child.context.defineProperty('themeToken', { value: { borderRadiusLG: 8 } });
 
-    render(
+    const { findByTestId } = render(
       <ConfigProvider>
         <App>
           <FlowEngineProvider engine={engine}>
@@ -173,7 +183,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
       </ConfigProvider>,
     );
 
-    await clickDeleteFromLastDropdown();
+    await hoverHostAndClickDelete(await findByTestId('result'));
     expect(engine.getModel(child.uid)).toBeUndefined();
     const remain = (parent.subModels as any).items || [];
     expect(remain.find((m: FlowModel) => m.uid === child.uid)).toBeUndefined();
@@ -200,7 +210,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
     }
 
     const engine = new FlowEngine();
-    engine.flowSettings.forceEnable();
+    await engine.flowSettings.forceEnable();
     engine.registerModels({ ParentModel, RenderFnChild });
     const parent = engine.createModel({ use: 'ParentModel', uid: 'parent-4' }) as ParentModel;
     const child = engine.createModel({ use: 'RenderFnChild', uid: 'cell-4' }) as RenderFnChild;
@@ -208,7 +218,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
     parent.context.defineProperty('themeToken', { value: { borderRadiusLG: 8 } });
     child.context.defineProperty('themeToken', { value: { borderRadiusLG: 8 } });
 
-    render(
+    const { findByTestId } = render(
       <ConfigProvider>
         <App>
           <FlowEngineProvider engine={engine}>
@@ -218,7 +228,7 @@ describe('Delete problematic model via FlowSettings menu', () => {
       </ConfigProvider>,
     );
 
-    await clickDeleteFromLastDropdown();
+    await hoverHostAndClickDelete(await findByTestId('result'));
     expect(engine.getModel(child.uid)).toBeUndefined();
     const remain = (parent.subModels as any).cells || [];
     expect(remain.find((m: FlowModel) => m.uid === child.uid)).toBeUndefined();

package/src/components/__tests__/gridDragPlanner.test.ts

@@ -15,6 +15,7 @@ import {
   getSlotKey,
   resolveDropIntent,
   Point,
+  buildLayoutSnapshot,
 } from '../dnd/gridDragPlanner';
 
 const rect = { top: 0, left: 0, width: 100, height: 100 };
@@ -29,6 +30,93 @@ const createLayout = (
   rowOrder,
 });
 
+const createDomRect = ({ top, left, width, height }: { top: number; left: number; width: number; height: number }) => {
+  return {
+    top,
+    left,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect;
+};
+
+const mockRect = (
+  element: Element,
+  rect: {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+  },
+) => {
+  Object.defineProperty(element, 'getBoundingClientRect', {
+    configurable: true,
+    value: () => createDomRect(rect),
+  });
+};
+
+describe('buildLayoutSnapshot', () => {
+  it('should ignore nested grid columns/items even when rowId is duplicated', () => {
+    const container = document.createElement('div');
+    const row = document.createElement('div');
+    row.setAttribute('data-grid-row-id', 'row-1');
+    container.appendChild(row);
+
+    const column = document.createElement('div');
+    column.setAttribute('data-grid-column-row-id', 'row-1');
+    column.setAttribute('data-grid-column-index', '0');
+    row.appendChild(column);
+
+    const item = document.createElement('div');
+    item.setAttribute('data-grid-item-row-id', 'row-1');
+    item.setAttribute('data-grid-column-index', '0');
+    item.setAttribute('data-grid-item-index', '0');
+    column.appendChild(item);
+
+    // 在外层 item 内构建一个嵌套 grid，并复用相同 rowId/columnIndex
+    const nestedRow = document.createElement('div');
+    nestedRow.setAttribute('data-grid-row-id', 'row-1');
+    item.appendChild(nestedRow);
+
+    const nestedColumn = document.createElement('div');
+    nestedColumn.setAttribute('data-grid-column-row-id', 'row-1');
+    nestedColumn.setAttribute('data-grid-column-index', '0');
+    nestedRow.appendChild(nestedColumn);
+
+    const nestedItem = document.createElement('div');
+    nestedItem.setAttribute('data-grid-item-row-id', 'row-1');
+    nestedItem.setAttribute('data-grid-column-index', '0');
+    nestedItem.setAttribute('data-grid-item-index', '0');
+    nestedColumn.appendChild(nestedItem);
+
+    mockRect(container, { top: 0, left: 0, width: 600, height: 600 });
+    mockRect(row, { top: 10, left: 10, width: 320, height: 120 });
+    mockRect(column, { top: 10, left: 10, width: 320, height: 120 });
+    mockRect(item, { top: 20, left: 20, width: 300, height: 80 });
+
+    // 嵌套 grid 给一个明显偏离的位置，用于判断是否被错误命中
+    mockRect(nestedRow, { top: 360, left: 360, width: 200, height: 120 });
+    mockRect(nestedColumn, { top: 360, left: 360, width: 200, height: 120 });
+    mockRect(nestedItem, { top: 370, left: 370, width: 180, height: 90 });
+
+    const snapshot = buildLayoutSnapshot({ container });
+    const columnEdgeSlots = snapshot.slots.filter((slot) => slot.type === 'column-edge');
+    const columnSlots = snapshot.slots.filter((slot) => slot.type === 'column');
+
+    // 外层单行单列单项应只有 6 个 slot：上/下 row-gap + 左/右 column-edge + before/after column
+    expect(snapshot.slots).toHaveLength(6);
+    expect(columnEdgeSlots).toHaveLength(2);
+    expect(columnSlots).toHaveLength(2);
+
+    // 不应混入嵌套 grid（其 top >= 360）
+    expect(snapshot.slots.every((slot) => slot.rect.top < 300)).toBe(true);
+  });
+});
+
 describe('getSlotKey', () => {
   it('should generate unique key for column slot', () => {
     const slot: LayoutSlot = {

package/src/components/dnd/gridDragPlanner.ts

@@ -333,7 +333,10 @@ export const buildLayoutSnapshot = ({ container }: BuildLayoutSnapshotOptions):
 
     const columnElements = Array.from(
       container.querySelectorAll(`[data-grid-column-row-id="${rowId}"][data-grid-column-index]`),
-    ) as HTMLElement[];
+    ).filter((el) => {
+      // 只保留当前 row 下的直接列，避免嵌套 Grid 中相同 rowId 的列混入
+      return (el as HTMLElement).closest('[data-grid-row-id]') === rowElement;
+    }) as HTMLElement[];
 
     const sortedColumns = columnElements.sort((a, b) => {
       const indexA = Number(a.dataset.gridColumnIndex || 0);
@@ -363,7 +366,10 @@ export const buildLayoutSnapshot = ({ container }: BuildLayoutSnapshotOptions):
 
       const itemElements = Array.from(
         columnElement.querySelectorAll(`[data-grid-item-row-id="${rowId}"][data-grid-column-index="${columnIndex}"]`),
-      ) as HTMLElement[];
+      ).filter((el) => {
+        // 只保留当前 column 下的直接 item，避免命中更深层嵌套 column 的 item
+        return (el as HTMLElement).closest('[data-grid-column-row-id][data-grid-column-index]') === columnElement;
+      }) as HTMLElement[];
 
       const sortedItems = itemElements.sort((a, b) => {
         const indexA = Number(a.dataset.gridItemIndex || 0);

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';
@@ -188,15 +189,42 @@ 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)
+  );
+};
+
 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 +238,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;
@@ -833,6 +884,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={{