@nocobase/flow-engine 2.1.0-beta.2 → 2.1.0-beta.21

package/README.md

@@ -1,17 +1,24 @@
 # NocoBase
 
 <video width="100%" controls>
-      <source src="https://static-docs.nocobase.com/NocoBase0510.mp4" type="video/mp4">
+  <source src="https://github.com/user-attachments/assets/4d11a87b-00e2-48f3-9bf7-389d21072d13" type="video/mp4">
 </video>
 
+<p align="center">
+<a href="https://trendshift.io/repositories/4112" target="_blank"><img src="https://trendshift.io/api/badge/repositories/4112" alt="nocobase%2Fnocobase | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.producthunt.com/posts/nocobase?embed=true&utm_source=badge-top-post-topic-badge&utm_medium=badge&utm_souce=badge-nocobase" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-topic-badge.svg?post_id=456520&theme=light&period=weekly&topic_id=267" alt="NocoBase - Scalability&#0045;first&#0044;&#0032;open&#0045;source&#0032;no&#0045;code&#0032;platform | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+</p>
 
 ## What is NocoBase
 
-NocoBase is a scalability-first, open-source no-code development platform.  
-Instead of investing years of time and millions of dollars in research and development, deploy NocoBase in a few minutes and you'll have a private, controllable, and extremely scalable no-code development platform!
+NocoBase is the most extensible AI-powered no-code platform.   
+Total control. Infinite extensibility. AI collaboration.  
+Enable your team to adapt quickly and cut costs dramatically.  
+No years of development. No millions wasted.  
+Deploy NocoBase in minutes — and take control of everything.
 
 Homepage:  
-https://www.nocobase.com/
+https://www.nocobase.com/  
 
 Online Demo:  
 https://demo.nocobase.com/new
@@ -19,12 +26,74 @@ https://demo.nocobase.com/new
 Documents:  
 https://docs.nocobase.com/
 
-Commericial license & plugins:  
-https://www.nocobase.com/en/commercial
+Forum:  
+https://forum.nocobase.com/
 
-License agreement:   
-https://www.nocobase.com/en/agreement
+Use Cases:  
+https://www.nocobase.com/en/blog/tags/customer-stories
 
+## Release Notes
 
-## Contact Us:  
-hello@nocobase.com
+Our [blog](https://www.nocobase.com/en/blog/timeline) is regularly updated with release notes and provides a weekly summary.
+
+## Distinctive features
+
+### 1. Data model-driven, not form/table–driven
+
+Instead of being constrained by forms or tables, NocoBase adopts a data model–driven approach, separating data structure from user interface to unlock unlimited possibilities.
+
+- UI and data structure are fully decoupled
+- Multiple blocks and actions can be created for the same table or record in any quantity or form
+- Supports the main database, external databases, and third-party APIs as data sources
+
+![model](https://static-docs.nocobase.com/model.png)
+
+### 2. AI employees, integrated into your business systems
+Unlike standalone AI demos, NocoBase allows you to embed AI capabilities seamlessly into your interfaces, workflows, and data context, making AI truly useful in real business scenarios.
+
+- Define AI employees for roles such as translator, analyst, researcher, or assistant
+- Seamless AI–human collaboration in interfaces and workflows
+- Ensure AI usage is secure, transparent, and customizable for your business needs
+
+![AI-employee](https://static-docs.nocobase.com/ai-employee-home.png)
+
+### 3. What you see is what you get, incredibly easy to use
+
+While enabling the development of complex business systems, NocoBase keeps the experience simple and intuitive.
+
+- One-click switch between usage mode and configuration mode
+- Pages serve as a canvas to arrange blocks and actions, similar to Notion
+- Configuration mode is designed for ordinary users, not just programmers
+
+![wysiwyg](https://static-docs.nocobase.com/wysiwyg.gif)
+
+### 4. Everything is a plugin, designed for extension
+Adding more no-code features will never cover every business case. NocoBase is built for extension through its plugin-based microkernel architecture.
+
+- All functionalities are plugins, similar to WordPress
+- Plugins are ready to use upon installation
+- Pages, blocks, actions, APIs, and data sources can all be extended through custom plugins
+
+![plugins](https://static-docs.nocobase.com/plugins.png)
+
+## Installation
+
+NocoBase supports three installation methods:
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/docker-compose">Installing With Docker (👍Recommended)</a>
+
+  Suitable for no-code scenarios, no code to write. When upgrading, just download the latest image and reboot.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/create-nocobase-app">Installing from create-nocobase-app CLI</a>
+
+  The business code of the project is completely independent and supports low-code development.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/git-clone">Installing from Git source code</a>
+
+  If you want to experience the latest unreleased version, or want to participate in the contribution, you need to make changes and debug on the source code, it is recommended to choose this installation method, which requires a high level of development skills, and if the code has been updated, you can git pull the latest code.
+
+## How NocoBase works
+
+<video width="100%" controls>
+  <source src="https://github.com/user-attachments/assets/8d183b44-9bb5-4792-b08f-bc08fe8dfaaf" type="video/mp4">
+</video>

package/lib/JSRunner.d.ts

@@ -13,11 +13,20 @@ export interface JSRunnerOptions {
     version?: string;
     /**
      * Enable RunJS template compatibility preprocessing for `{{ ... }}`.
-     * When enabled via `ctx.runjs(code, vars, { preprocessTemplates: true })` (default),
+     * When enabled (or falling back to version default),
      * the code will be rewritten to call `ctx.resolveJsonTemplate(...)` at runtime.
      */
     preprocessTemplates?: boolean;
 }
+/**
+ * Decide whether RunJS `{{ ... }}` compatibility preprocessing should run.
+ *
+ * Priority:
+ * 1. Explicit `preprocessTemplates` option always wins.
+ * 2. Otherwise, `version === 'v2'` disables preprocessing.
+ * 3. Fallback keeps v1-compatible behavior (enabled).
+ */
+export declare function shouldPreprocessRunJSTemplates(options?: Pick<JSRunnerOptions, 'preprocessTemplates' | 'version'>): boolean;
 export declare class JSRunner {
     private globals;
     private timeoutMs;

package/lib/JSRunner.js

@@ -27,11 +27,53 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var JSRunner_exports = {};
 __export(JSRunner_exports, {
-  JSRunner: () => JSRunner
+  JSRunner: () => JSRunner,
+  shouldPreprocessRunJSTemplates: () => shouldPreprocessRunJSTemplates
 });
 module.exports = __toCommonJS(JSRunner_exports);
 var import_ses = require("ses");
 var import_exceptions = require("./utils/exceptions");
+function shouldPreprocessRunJSTemplates(options) {
+  if (typeof (options == null ? void 0 : options.preprocessTemplates) === "boolean") {
+    return options.preprocessTemplates;
+  }
+  return (options == null ? void 0 : options.version) !== "v2";
+}
+__name(shouldPreprocessRunJSTemplates, "shouldPreprocessRunJSTemplates");
+const BARE_CTX_TEMPLATE_RE = /(^|[=(:,[\s)])(\{\{\s*(ctx(?:\.|\[|\?\.)[^}]*)\s*\}\})/m;
+function extractDeprecatedCtxTemplateUsage(code) {
+  const src = String(code || "");
+  const m = src.match(BARE_CTX_TEMPLATE_RE);
+  if (!m) return null;
+  const placeholder = String(m[2] || "").trim();
+  const expression = String(m[3] || "").trim();
+  if (!placeholder || !expression) return null;
+  return { placeholder, expression };
+}
+__name(extractDeprecatedCtxTemplateUsage, "extractDeprecatedCtxTemplateUsage");
+function shouldHintCtxTemplateSyntax(err, usage) {
+  const isSyntaxError = err instanceof SyntaxError || String((err == null ? void 0 : err.name) || "") === "SyntaxError";
+  if (!isSyntaxError) return false;
+  if (!usage) return false;
+  const msg = String((err == null ? void 0 : err.message) || err || "");
+  return /unexpected token/i.test(msg);
+}
+__name(shouldHintCtxTemplateSyntax, "shouldHintCtxTemplateSyntax");
+function toCtxTemplateSyntaxHintError(err, usage) {
+  const hint = `"${usage.placeholder}" has been deprecated and cannot be used as executable RunJS syntax. Use await ctx.getVar("${usage.expression}") instead, or keep "${usage.placeholder}" as a plain string.`;
+  const out = new SyntaxError(hint);
+  try {
+    out.cause = err;
+  } catch (_) {
+  }
+  try {
+    out.__runjsHideLocation = true;
+    out.stack = `${out.name}: ${out.message}`;
+  } catch (_) {
+  }
+  return out;
+}
+__name(toCtxTemplateSyntaxHintError, "toCtxTemplateSyntaxHintError");
 const _JSRunner = class _JSRunner {
   globals;
   timeoutMs;
@@ -111,11 +153,13 @@ const _JSRunner = class _JSRunner {
       if (err instanceof import_exceptions.FlowExitAllException) {
         throw err;
       }
-      console.error(err);
+      const usage = extractDeprecatedCtxTemplateUsage(code);
+      const outErr = shouldHintCtxTemplateSyntax(err, usage) && usage ? toCtxTemplateSyntaxHintError(err, usage) : err;
+      console.error(outErr);
       return {
         success: false,
-        error: err,
-        timeout: err.message === "Execution timed out"
+        error: outErr,
+        timeout: (outErr == null ? void 0 : outErr.message) === "Execution timed out"
       };
     }
   }
@@ -124,5 +168,6 @@ __name(_JSRunner, "JSRunner");
 let JSRunner = _JSRunner;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  JSRunner
+  JSRunner,
+  shouldPreprocessRunJSTemplates
 });

package/lib/ViewScopedFlowEngine.js

@@ -65,7 +65,11 @@ function createViewScopedEngine(parent) {
     "_previousEngine",
     "_nextEngine",
     // getModel 需要在本地执行以确保全局查找时正确遍历整个引擎栈
-    "getModel"
+    "getModel",
+    // 视图销毁回调需要在本地存储，每个视图引擎有自己的销毁逻辑
+    "_destroyView",
+    "setDestroyView",
+    "destroyView"
   ]);
   const handler = {
     get(target, prop, receiver) {

package/lib/components/FlowModelRenderer.d.ts

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

package/lib/components/FlowModelRenderer.js

@@ -61,11 +61,12 @@ const FlowModelRendererWithAutoFlows = (0, import_reactive.observer)(
     showErrorFallback,
     settingsMenuLevel,
     extraToolbarItems,
-    fallback
+    fallback,
+    useCache
   }) => {
     const { loading: pending, error: autoFlowsError } = (0, import_hooks.useApplyAutoFlows)(model, inputArgs, {
       throwOnError: false,
-      useCache: model.context.useCache
+      useCache
     });
     (0, import_utils.setAutoFlowError)(model, autoFlowsError || null);
     if (pending) {
@@ -195,13 +196,15 @@ const FlowModelRenderer = (0, import_reactive.observer)(
     extraToolbarItems,
     useCache
   }) => {
+    var _a;
+    const resolvedUseCache = typeof useCache === "boolean" ? useCache : (_a = model == null ? void 0 : model.context) == null ? void 0 : _a.useCache;
     (0, import_react.useEffect)(() => {
-      if (model == null ? void 0 : model.context) {
+      if ((model == null ? void 0 : model.context) && typeof resolvedUseCache !== "undefined") {
         model.context.defineProperty("useCache", {
-          value: typeof useCache === "boolean" ? useCache : model.context.useCache
+          value: resolvedUseCache
         });
       }
-    }, [model == null ? void 0 : model.context, useCache]);
+    }, [model == null ? void 0 : model.context, resolvedUseCache]);
     if (!model || typeof model.render !== "function") {
       console.warn("FlowModelRenderer: Invalid model or render method not found.", model);
       return null;
@@ -218,7 +221,8 @@ const FlowModelRenderer = (0, import_reactive.observer)(
         showErrorFallback,
         settingsMenuLevel,
         extraToolbarItems,
-        fallback
+        fallback,
+        useCache: resolvedUseCache
       }
     );
     if (showErrorFallback) {

package/lib/components/MobilePopup.js

@@ -41,11 +41,12 @@ __export(MobilePopup_exports, {
 });
 module.exports = __toCommonJS(MobilePopup_exports);
 var import_antd = require("antd");
-var import_antd_mobile = require("antd-mobile");
 var import_react = __toESM(require("react"));
-var import_antd_mobile_icons = require("antd-mobile-icons");
 var import_MobilePopup = require("./MobilePopup.style");
 var import_react_i18next = require("react-i18next");
+var import_lazy_helper = require("../lazy-helper");
+const { Popup } = (0, import_lazy_helper.lazy)(() => import("antd-mobile"), "Popup");
+const { CloseOutline } = (0, import_lazy_helper.lazy)(() => import("antd-mobile-icons"), "CloseOutline");
 const MobilePopup = /* @__PURE__ */ __name((props) => {
   const { title, visible, onClose: closePopup, children, minHeight, className, footer } = props;
   const { t } = (0, import_react_i18next.useTranslation)();
@@ -67,7 +68,7 @@ const MobilePopup = /* @__PURE__ */ __name((props) => {
     };
   }, []);
   return /* @__PURE__ */ import_react.default.createElement(import_antd.ConfigProvider, { theme }, /* @__PURE__ */ import_react.default.createElement(
-    import_antd_mobile.Popup,
+    Popup,
     {
       className: `${componentCls} ${hashId} ${className || ""}`,
       visible,
@@ -81,7 +82,7 @@ const MobilePopup = /* @__PURE__ */ __name((props) => {
       style,
       destroyOnClose: true
     },
-    /* @__PURE__ */ import_react.default.createElement("div", { className: "nb-mobile-action-drawer-header" }, /* @__PURE__ */ import_react.default.createElement("span", { className: "nb-mobile-action-drawer-placeholder" }, /* @__PURE__ */ import_react.default.createElement(import_antd_mobile_icons.CloseOutline, null)), /* @__PURE__ */ import_react.default.createElement("span", null, title), /* @__PURE__ */ import_react.default.createElement(
+    /* @__PURE__ */ import_react.default.createElement("div", { className: "nb-mobile-action-drawer-header" }, /* @__PURE__ */ import_react.default.createElement("span", { className: "nb-mobile-action-drawer-placeholder" }, /* @__PURE__ */ import_react.default.createElement(CloseOutline, null)), /* @__PURE__ */ import_react.default.createElement("span", null, title), /* @__PURE__ */ import_react.default.createElement(
       "span",
       {
         className: "nb-mobile-action-drawer-close-icon",
@@ -90,7 +91,7 @@ const MobilePopup = /* @__PURE__ */ __name((props) => {
         tabIndex: 0,
         "aria-label": t("Close")
       },
-      /* @__PURE__ */ import_react.default.createElement(import_antd_mobile_icons.CloseOutline, null)
+      /* @__PURE__ */ import_react.default.createElement(CloseOutline, null)
     )),
     children,
     footer && /* @__PURE__ */ import_react.default.createElement("div", { className: "nb-mobile-action-drawer-footer" }, footer)

package/lib/components/dnd/gridDragPlanner.js

@@ -220,7 +220,9 @@ const buildLayoutSnapshot = /* @__PURE__ */ __name(({ container }) => {
     }
     const columnElements = Array.from(
       container.querySelectorAll(`[data-grid-column-row-id="${rowId}"][data-grid-column-index]`)
-    );
+    ).filter((el) => {
+      return el.closest("[data-grid-row-id]") === rowElement;
+    });
     const sortedColumns = columnElements.sort((a, b) => {
       const indexA = Number(a.dataset.gridColumnIndex || 0);
       const indexB = Number(b.dataset.gridColumnIndex || 0);
@@ -245,7 +247,9 @@ const buildLayoutSnapshot = /* @__PURE__ */ __name(({ container }) => {
       });
       const itemElements = Array.from(
         columnElement.querySelectorAll(`[data-grid-item-row-id="${rowId}"][data-grid-column-index="${columnIndex}"]`)
-      );
+      ).filter((el) => {
+        return el.closest("[data-grid-column-row-id][data-grid-column-index]") === columnElement;
+      });
       const sortedItems = itemElements.sort((a, b) => {
         const indexA = Number(a.dataset.gridItemIndex || 0);
         const indexB = Number(b.dataset.gridItemIndex || 0);

package/lib/components/settings/wrappers/contextual/DefaultSettingsIcon.d.ts

@@ -6,6 +6,7 @@
  * 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 type { DropdownProps } from 'antd';
 import React from 'react';
 import { FlowModel } from '../../../../models';
 /**
@@ -18,6 +19,8 @@ interface DefaultSettingsIconProps {
     showCopyUidButton?: boolean;
     menuLevels?: number;
     flattenSubMenus?: boolean;
+    onDropdownVisibleChange?: (open: boolean) => void;
+    getPopupContainer?: DropdownProps['getPopupContainer'];
     [key: string]: any;
 }
 export declare const DefaultSettingsIcon: React.FC<DefaultSettingsIconProps>;

package/lib/components/settings/wrappers/contextual/DefaultSettingsIcon.js

@@ -41,6 +41,7 @@ __export(DefaultSettingsIcon_exports, {
 });
 module.exports = __toCommonJS(DefaultSettingsIcon_exports);
 var import_icons = require("@ant-design/icons");
+var import_css = require("@emotion/css");
 var import_antd = require("antd");
 var import_react = __toESM(require("react"));
 var import_models = require("../../../../models");
@@ -149,13 +150,32 @@ const MenuLabelItem = /* @__PURE__ */ __name(({ title, uiMode, itemProps }) => {
   }
   return /* @__PURE__ */ import_react.default.createElement("span", { style: { display: "inline-flex", alignItems: "center", gap: 6 } }, content, /* @__PURE__ */ import_react.default.createElement(import_antd.Tooltip, { title: disabledReason, placement: "right", destroyTooltipOnHide: true }, /* @__PURE__ */ import_react.default.createElement(import_icons.QuestionCircleOutlined, { style: { color: disabledIconColor } })));
 }, "MenuLabelItem");
+const TOOLBAR_ICONS_SELECTOR = ".nb-toolbar-container-icons";
+const TOOLBAR_CONTAINER_SELECTOR = ".nb-toolbar-container";
+const TOOLBAR_DROPDOWN_OVERLAY_CLASS = import_css.css`
+  width: max-content;
+  min-width: max-content;
+
+  .ant-dropdown-menu {
+    width: max-content;
+    min-width: max-content;
+  }
+`;
+const getToolbarPopupContainer = /* @__PURE__ */ __name((triggerNode) => {
+  if (!triggerNode) {
+    return null;
+  }
+  return triggerNode.closest(TOOLBAR_ICONS_SELECTOR) || triggerNode.closest(TOOLBAR_CONTAINER_SELECTOR);
+}, "getToolbarPopupContainer");
 const DefaultSettingsIcon = /* @__PURE__ */ __name(({
   model,
   showDeleteButton = true,
   showCopyUidButton = true,
   menuLevels = 1,
   // 默认一级菜单
-  flattenSubMenus = true
+  flattenSubMenus = true,
+  onDropdownVisibleChange,
+  getPopupContainer
 }) => {
   const { message } = import_antd.App.useApp();
   const t = (0, import_react.useMemo)(() => (0, import_utils.getT)(model), [model]);
@@ -168,14 +188,30 @@ const DefaultSettingsIcon = /* @__PURE__ */ __name(({
   const [isLoading, setIsLoading] = (0, import_react.useState)(true);
   const closeDropdown = (0, import_react.useCallback)(() => {
     setVisible(false);
-  }, []);
-  const handleOpenChange = (0, import_react.useCallback)((nextOpen, info) => {
-    if (info.source === "trigger" || nextOpen) {
-      (0, import_react.startTransition)(() => {
-        setVisible(nextOpen);
-      });
-    }
-  }, []);
+    onDropdownVisibleChange == null ? void 0 : onDropdownVisibleChange(false);
+  }, [onDropdownVisibleChange]);
+  const resolvePopupContainer = (0, import_react.useCallback)(
+    (triggerNode) => {
+      return getToolbarPopupContainer(triggerNode) || (getPopupContainer == null ? void 0 : getPopupContainer(triggerNode)) || (triggerNode == null ? void 0 : triggerNode.parentElement) || document.body;
+    },
+    [getPopupContainer]
+  );
+  const handleOpenChange = (0, import_react.useCallback)(
+    (nextOpen, info) => {
+      if (info.source === "trigger" || nextOpen) {
+        (0, import_react.startTransition)(() => {
+          setVisible(nextOpen);
+        });
+        onDropdownVisibleChange == null ? void 0 : onDropdownVisibleChange(nextOpen);
+      }
+    },
+    [onDropdownVisibleChange]
+  );
+  (0, import_react.useEffect)(() => {
+    return () => {
+      onDropdownVisibleChange == null ? void 0 : onDropdownVisibleChange(false);
+    };
+  }, [onDropdownVisibleChange]);
   const dropdownMaxHeight = (0, import_hooks.useNiceDropdownMaxHeight)([visible]);
   (0, import_react.useEffect)(() => {
     let mounted = true;
@@ -671,6 +707,9 @@ const DefaultSettingsIcon = /* @__PURE__ */ __name(({
   return /* @__PURE__ */ import_react.default.createElement(
     import_antd.Dropdown,
     {
+      getPopupContainer: resolvePopupContainer,
+      overlayClassName: TOOLBAR_DROPDOWN_OVERLAY_CLASS,
+      overlayStyle: { width: "max-content", minWidth: "max-content" },
       onOpenChange: handleOpenChange,
       open: visible,
       menu: {

package/lib/components/settings/wrappers/contextual/FlowsFloatContextMenu.d.ts

@@ -9,13 +9,14 @@
 import React from 'react';
 import { FlowModel } from '../../../../models';
 import { ToolbarItemConfig } from '../../../../types';
-interface ModelProvidedProps {
-    model: FlowModel<any>;
+type ToolbarPosition = 'inside' | 'above' | 'below';
+interface BaseFloatContextMenuProps {
     children?: React.ReactNode;
     enabled?: boolean;
     showDeleteButton?: boolean;
     showCopyUidButton?: boolean;
     containerStyle?: React.CSSProperties;
+    /** 自定义工具栏样式，`top/left/right/bottom` 会作为 portal overlay 的 inset 使用。 */
     toolbarStyle?: React.CSSProperties;
     className?: string;
     /**
@@ -45,65 +46,40 @@ interface ModelProvidedProps {
     /**
      * @default 'inside'
      */
-    toolbarPosition?: 'inside' | 'above' | 'below';
+    toolbarPosition?: ToolbarPosition;
+}
+interface ModelProvidedProps extends BaseFloatContextMenuProps {
+    model: FlowModel<any>;
 }
-interface ModelByIdProps {
+interface ModelByIdProps extends BaseFloatContextMenuProps {
     uid: string;
     modelClassName: string;
-    children?: React.ReactNode;
-    enabled?: boolean;
-    showDeleteButton?: boolean;
-    showCopyUidButton?: boolean;
-    containerStyle?: React.CSSProperties;
-    className?: string;
-    /**
-     * @default true
-     */
-    showBorder?: boolean;
-    /**
-     * @default true
-     */
-    showBackground?: boolean;
-    /**
-     * @default false
-     */
-    showTitle?: boolean;
-    /**
-     * Settings menu levels: 1=current model only (default), 2=include sub-models
-     */
-    settingsMenuLevel?: number;
-    /**
-     * Extra toolbar items to add to this context menu instance
-     */
-    extraToolbarItems?: ToolbarItemConfig[];
-    /**
-     * @default 'inside'
-     */
-    toolbarPosition?: 'inside' | 'above' | 'below';
 }
 type FlowsFloatContextMenuProps = ModelProvidedProps | ModelByIdProps;
 /**
- * FlowsFloatContextMenu组件 - 悬浮配置图标组件
+ * FlowsFloatContextMenu组件 - 悬浮配置工具栏组件
  *
  * 功能特性：
  * - 鼠标悬浮显示右上角配置图标
  * - 点击图标显示配置菜单
  * - 支持删除功能
  * - Wrapper 模式支持
- * - 使用与 NocoBase x-settings 一致的样式
- * - 按flow分组显示steps
+ * - 使用 portal overlay 避免被宿主或祖先裁剪
+ * - 设置菜单与工具栏共享同一个 popup 容器
  *
  * 支持两种使用方式：
- * 1. 直接提供model: <FlowsFloatContextMenu model={myModel}>{children}</FlowsFloatContextMenu>
- * 2. 通过uid和modelClassName获取model: <FlowsFloatContextMenu uid="model1" modelClassName="MyModel">{children}</FlowsFloatContextMenu>
+ * 1. 直接提供 model: `<FlowsFloatContextMenu model={myModel}>{children}</FlowsFloatContextMenu>`
+ * 2. 通过 uid 和 modelClassName 获取 model:
+ *    `<FlowsFloatContextMenu uid="model1" modelClassName="MyModel">{children}</FlowsFloatContextMenu>`
  *
  * @param props.children 子组件，必须提供
- * @param props.enabled 是否启用悬浮菜单，默认为true
- * @param props.showDeleteButton 是否显示删除按钮，默认为true
- * @param props.showCopyUidButton 是否显示复制UID按钮，默认为true
+ * @param props.enabled 是否启用悬浮菜单，默认为 true
+ * @param props.showDeleteButton 是否显示删除按钮，默认为 true
+ * @param props.showCopyUidButton 是否显示复制 UID 按钮，默认为 true
  * @param props.containerStyle 容器自定义样式
+ * @param props.toolbarStyle 工具栏自定义样式；`top/left/right/bottom` 会作为 portal overlay 的 inset 使用
  * @param props.className 容器自定义类名
- * @param props.showTitle 是否在边框左上角显示模型title，默认为false
+ * @param props.showTitle 是否在边框左上角显示模型 title，默认为 false
  * @param props.settingsMenuLevel 设置菜单层级：1=仅当前模型(默认)，2=包含子模型
  * @param props.extraToolbarItems 额外的工具栏项目，仅应用于此实例
  */