@nocobase/flow-engine 2.1.0-beta.41 → 2.1.0-beta.43

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

@@ -556,6 +556,57 @@ describe('transformItems - searchable flags', () => {
     await waitFor(() => expect(screen.getByText('Field 1')).toBeInTheDocument());
     expect(screen.getByRole('textbox')).toHaveValue('');
   });
+
+  it('keeps root group search value when hovering a sibling submenu', async () => {
+    const engine = new FlowEngine();
+    await engine.flowSettings.forceEnable();
+    class Parent extends FlowModel {}
+    engine.registerModels({ Parent });
+    const parent = engine.createModel<FlowModel>({ use: 'Parent' });
+
+    const items = [
+      {
+        key: 'fields',
+        label: '',
+        type: 'group' as const,
+        searchable: true,
+        searchPlaceholder: 'Search fields',
+        children: [
+          { key: 'nickname', label: 'Nickname', createModelOptions: { use: 'Parent' } },
+          { key: 'email', label: 'Email', createModelOptions: { use: 'Parent' } },
+        ],
+      },
+      {
+        key: 'association-fields',
+        label: 'Display association fields',
+        children: [{ key: 'author', label: 'Author', createModelOptions: { use: 'Parent' } }],
+      },
+    ];
+
+    const user = userEvent.setup();
+    render(
+      <FlowEngineProvider engine={engine}>
+        <ConfigProvider>
+          <App>
+            <AddSubModelButton model={parent} subModelKey="items" items={items as any}>
+              Open
+            </AddSubModelButton>
+          </App>
+        </ConfigProvider>
+      </FlowEngineProvider>,
+    );
+
+    await user.click(screen.getByText('Open'));
+    const searchInput = await screen.findByPlaceholderText('Search fields');
+    await user.type(searchInput, 'nick');
+    await waitFor(() => expect(screen.queryByText('Email')).not.toBeInTheDocument());
+
+    await user.hover(screen.getByText('Display association fields'));
+
+    await waitFor(() => expect(screen.getByText('Author')).toBeInTheDocument());
+    expect(searchInput).toHaveValue('nick');
+    expect(screen.getByText('Nickname')).toBeInTheDocument();
+  });
 });
 
 describe('transformItems - hide', () => {

package/src/flowContext.ts

@@ -400,6 +400,10 @@ export type FlowContextGetApiInfosOptions = {
    * RunJS 文档版本（默认 v1）。
    */
   version?: RunJSVersion;
+  /**
+   * Include editor completion metadata. Defaults to false so API-doc callers keep the compact public shape.
+   */
+  includeCompletion?: boolean;
 };
 
 export type FlowContextGetVarInfosOptions = {
@@ -704,10 +708,11 @@ export class FlowContext {
    * - 输出仅来自 RunJS doc 与 defineProperty/defineMethod 的 info
    * - 不读取/展开 PropertyMeta（变量结构）
    * - 不自动展开深层 properties
-   * - 不返回自动补全字段（例如 completion）
+   * - 默认不返回自动补全字段（例如 completion），传入 includeCompletion=true 时返回
    */
   async getApiInfos(options: FlowContextGetApiInfosOptions = {}): Promise<Record<string, FlowContextApiInfo>> {
     const version = (options.version as RunJSVersion) || ('v1' as RunJSVersion);
+    const includeCompletion = !!options.includeCompletion;
     const evalCtx = this.createProxy();
 
     const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
@@ -759,7 +764,14 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -773,7 +785,17 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['title', 'type', 'interface', 'description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'title',
+        'type',
+        'interface',
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -872,7 +894,7 @@ export class FlowContext {
       node = { ...node, ...pickPropertyInfo(docObj) };
       node = { ...node, ...pickPropertyInfo(infoObj) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       const outKey = mapDocKeyToApiKey(key, docNode);
       // Avoid exposing ctx.React/ctx.ReactDOM/ctx.antd in api docs when mapping to ctx.libs.*.
@@ -890,7 +912,7 @@ export class FlowContext {
       node = { ...node, ...pickMethodInfo(docObj) };
       node = { ...node, ...pickMethodInfo(info) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       node.type = 'function';
 
@@ -913,7 +935,7 @@ export class FlowContext {
         let node: FlowContextApiInfo = {};
         node = { ...node, ...pickPropertyInfo(childObj) };
         delete (node as any).properties;
-        delete (node as any).completion;
+        if (!includeCompletion) delete (node as any).completion;
         if (!node.description || !String(node.description).trim()) continue;
         out[outKey] = node;
       }
@@ -3075,6 +3097,17 @@ class BaseFlowEngineContext extends FlowContext {
         const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
         return runner.run(jsCode);
       },
+      {
+        description: 'Execute a RunJS code string in the current Flow context.',
+        detail: '(code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<RunJSResult>',
+        params: [
+          { name: 'code', type: 'string', description: 'RunJS code to execute.' },
+          { name: 'variables', type: 'Record<string, any>', optional: true, description: 'Additional globals.' },
+          { name: 'options', type: 'JSRunnerOptions', optional: true, description: 'Runner options.' },
+        ],
+        returns: { type: 'Promise<{ success: boolean; value?: any; error?: any; timeout?: boolean }>' },
+        completion: { insertText: `await ctx.runjs('return 1')` },
+      },
     );
   }
 }
@@ -3927,6 +3960,7 @@ export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRunt
 
 export type RunJSDocCompletionDoc = {
   insertText?: string;
+  requires?: Array<'element'>;
 };
 
 export type RunJSDocHiddenDoc = boolean | ((ctx: any) => boolean | Promise<boolean>);

package/src/flowEngine.ts

@@ -20,6 +20,7 @@ import { APIResource, FlowResource, MultiRecordResource, SingleRecordResource, S
 import { Emitter } from './emitter';
 import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
 import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
+import { createLoadedPageCache } from './utils/loadedPageCache';
 import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
@@ -135,6 +136,8 @@ export class FlowEngine {
    */
   private _savingModels = new Map<string, Promise<any>>();
 
+  private _loadedPageCache = createLoadedPageCache();
+
   /**
    * Flow engine context object.
    * @private
@@ -1339,7 +1342,8 @@ export class FlowEngine {
   async loadModel<T extends FlowModel = FlowModel>(options): Promise<T | null> {
     if (!this.ensureModelRepository()) return;
     const refresh = !!options?.refresh;
-    if (!refresh) {
+    const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (!refresh && !bypassLoadedPageCache) {
       const model = this.findModelByParentId(options.parentId, options.subKey);
       if (model) {
         return model as T;
@@ -1350,15 +1354,24 @@ export class FlowEngine {
       }
     }
     const data = await this._modelRepository.findOne(options);
-    if (!data?.uid) return null;
-    await this.resolveModelTree(data);
-    if (refresh) {
+    if (!data?.uid) {
+      if (bypassLoadedPageCache) {
+        this._loadedPageCache.clear(options);
+      }
+      return null;
+    }
+    if (refresh || bypassLoadedPageCache) {
       const existing = this.getModel(data.uid);
       if (existing) {
         this.removeModelWithSubModels(existing.uid);
       }
     }
-    return this.createModelAsync<T>(data as any);
+    const model = await this.createModelAsync<T>(data as any);
+    if (bypassLoadedPageCache) {
+      this._loadedPageCache.mountModelToParent(model, true);
+      this._loadedPageCache.clear(options);
+    }
+    return model;
   }
 
   /**
@@ -1398,22 +1411,31 @@ export class FlowEngine {
   ): Promise<T | null> {
     if (!this.ensureModelRepository()) return;
     const { uid, parentId, subKey } = options;
-    if (uid && this._modelInstances.has(uid)) {
+    const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (uid && !bypassLoadedPageCache && this._modelInstances.has(uid)) {
       return this._modelInstances.get(uid) as T;
     }
-    const m = this.findModelByParentId<T>(parentId, subKey);
-    if (m) {
-      return m;
-    }
+    if (!bypassLoadedPageCache) {
+      const m = this.findModelByParentId<T>(parentId, subKey);
+      if (m) {
+        return m;
+      }
 
-    const hydrated = await this.hydrateModelFromPreviousEngines<T>(options, extra);
-    if (hydrated) {
-      return hydrated;
+      const hydrated = await this.hydrateModelFromPreviousEngines<T>(options, extra);
+      if (hydrated) {
+        return hydrated;
+      }
     }
 
     const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
+      if (bypassLoadedPageCache) {
+        const existing = this.getModel(data.uid);
+        if (existing) {
+          this.removeModelWithSubModels(existing.uid);
+        }
+      }
       model = await this.createModelAsync<T>(data as any, extra);
     } else {
       model = await this.createModelAsync<T>(options, extra);
@@ -1421,18 +1443,9 @@ export class FlowEngine {
         await model.save();
       }
     }
-    if (model.parent) {
-      const subModel = model.parent.findSubModel(model.subKey, (m) => {
-        return m.uid === model.uid;
-      });
-      if (subModel) {
-        return model;
-      }
-      if (model.subType === 'array') {
-        model.parent.addSubModel(model.subKey, model);
-      } else {
-        model.parent.setSubModel(model.subKey, model);
-      }
+    this._loadedPageCache.mountModelToParent(model, bypassLoadedPageCache);
+    if (bypassLoadedPageCache) {
+      this._loadedPageCache.clear(options);
     }
     return model;
   }
@@ -1452,6 +1465,9 @@ export class FlowEngine {
     if (!this.ensureModelRepository()) return;
 
     const modelUid = model.uid;
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(model, {
+      force: !!options?.onlyStepParams,
+    });
 
     // 如果这个 model 正在保存中，返回现有的保存 Promise
     if (this._savingModels.has(modelUid)) {
@@ -1465,6 +1481,7 @@ export class FlowEngine {
 
     try {
       const result = await savePromise;
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
       return result;
     } finally {
       // 无论成功还是失败，都要清除保存状态
@@ -1501,11 +1518,16 @@ export class FlowEngine {
    * @returns {Promise<boolean>} Whether destroyed successfully
    */
   async destroyModel(uid: string) {
-    if (this.ensureModelRepository()) {
+    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(modelInstance);
+    const hasModelRepository = this.ensureModelRepository();
+    if (hasModelRepository) {
       await this._modelRepository.destroy(uid);
     }
 
-    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    if (hasModelRepository) {
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
+    }
     const parent = modelInstance?.parent;
     const result = this.removeModel(uid);
     parent && parent.emitter.emit('onSubModelDestroyed', modelInstance);
@@ -1620,6 +1642,7 @@ export class FlowEngine {
       console.warn(`FlowEngine: Cannot move model. Source or target model not found.`);
       return;
     }
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(sourceModel);
     const move = (sourceModel: FlowModel, targetModel: FlowModel) => {
       if (!sourceModel.parent || !targetModel.parent || sourceModel.parent !== targetModel.parent) {
         console.error('FlowModel.moveTo: Both models must have the same parent to perform move operation.');
@@ -1667,6 +1690,7 @@ export class FlowEngine {
     if (options?.persist !== false && this.ensureModelRepository()) {
       const position = sourceModel.sortIndex - targetModel.sortIndex > 0 ? 'after' : 'before';
       await this._modelRepository.move(sourceId, targetId, position);
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
     }
     // 触发事件以通知其他部分模型已移动
     sourceModel.parent.emitter.emit('onSubModelMoved', { source: sourceModel, target: targetModel });

package/src/runjs-context/contexts/FormJSFieldItemRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class FormJSFieldItemRunJSContext extends FlowRunJSContext {}
 
 FormJSFieldItemRunJSContext.define({
   label: 'FormJSFieldItem RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for form field rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for form field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     value: `Current field value (read-only in display mode; in controlled scenarios, use setProps to modify).`,
     record: `Current record data object (read-only).
       Contains all field values of the parent record.`,
@@ -38,7 +39,7 @@ FormJSFieldItemRunJSContext.define(
   {
     label: '表单 JS 字段项 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表单字段容器',
+      element: createZhCNElementPropertyDoc('ElementProxy，表单字段容器'),
       value: '字段值（展示模式为只读；受控场景用 setProps 修改）',
       record: '当前记录（只读）',
       formValues: {

package/src/runjs-context/contexts/JSBlockRunJSContext.ts

@@ -8,21 +8,16 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSBlockRunJSContext extends FlowRunJSContext {}
 
 JSBlockRunJSContext.define({
   label: 'RunJS context',
   properties: {
-    element: {
-      description: `ElementProxy instance providing a safe DOM container.
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container.
       Supports innerHTML, append, and other DOM manipulation methods.
-      Use this to render content in the JS block.`,
-      detail: 'ElementProxy',
-      properties: {
-        innerHTML: 'Set or read the HTML content of the container element.',
-      },
-    },
+      Use this to render content in the JS block.`),
     record: `Current record data object (read-only).
       Available when the JS block is within a data block or detail view context.`,
     value: 'Current value of the field or component, if available in the current context.',
@@ -44,13 +39,7 @@ JSBlockRunJSContext.define(
   {
     label: 'RunJS 上下文',
     properties: {
-      element: {
-        description: 'ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等',
-        detail: 'ElementProxy',
-        properties: {
-          innerHTML: '读取或设置容器的 HTML 内容',
-        },
-      },
+      element: createZhCNElementPropertyDoc('ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等'),
       record: '当前记录（只读，用于数据区块/详情等场景）',
       value: '当前值（若存在）',
       React: 'React 库',

package/src/runjs-context/contexts/JSColumnRunJSContext.ts

@@ -8,6 +8,7 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 /**
  * RunJS context for JSColumnModel (table custom column).
@@ -18,8 +19,9 @@ export class JSColumnRunJSContext extends FlowRunJSContext {}
 JSColumnRunJSContext.define({
   label: 'JSColumn RunJS context',
   properties: {
-    element:
+    element: createElementPropertyDoc(
       'ElementProxy instance providing a safe DOM container for the current table cell. Supports innerHTML/append and basic DOM APIs.',
+    ),
     record: 'Current row record object (read-only).',
     recordIndex: 'Index of the current row in the page (0-based).',
     collection: 'Collection definition metadata (read-only).',
@@ -40,7 +42,7 @@ JSColumnRunJSContext.define(
   {
     label: 'JS 列 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等',
+      element: createZhCNElementPropertyDoc('ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等'),
       record: '当前行记录对象（只读）',
       recordIndex: '当前行索引（从 0 开始）',
       collection: '集合定义元数据（只读）',

package/src/runjs-context/contexts/JSEditableFieldRunJSContext.ts

@@ -8,6 +8,7 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 /**
  * RunJS context for JSEditableFieldModel (form editable custom field).
@@ -19,11 +20,9 @@ export class JSEditableFieldRunJSContext extends FlowRunJSContext {}
 JSEditableFieldRunJSContext.define({
   label: 'JSEditableField RunJS context',
   properties: {
-    element: {
-      description:
-        'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
-      detail: 'ElementProxy',
-    },
+    element: createElementPropertyDoc(
+      'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
+    ),
     value: {
       description:
         'Current field value (read-only snapshot). In editable scenarios, prefer ctx.getValue()/ctx.setValue(v) for two-way binding.',
@@ -69,10 +68,7 @@ JSEditableFieldRunJSContext.define(
   {
     label: 'JS 可编辑字段 RunJS 上下文',
     properties: {
-      element: {
-        description: 'ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。',
-        detail: 'ElementProxy',
-      },
+      element: createZhCNElementPropertyDoc('ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。'),
       value: {
         description: '字段当前值（只读快照）。可编辑场景建议使用 ctx.getValue()/ctx.setValue(v) 做双向绑定。',
         detail: 'any',

package/src/runjs-context/contexts/JSFieldRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSFieldRunJSContext extends FlowRunJSContext {}
 
 JSFieldRunJSContext.define({
   label: 'JSField RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for field rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     value: `Current value of the field (read-only).
       Contains the data value stored in this field.`,
     record: `Current record data object (read-only).
@@ -34,7 +35,7 @@ JSFieldRunJSContext.define(
   {
     label: 'JS 字段 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作',
+      element: createZhCNElementPropertyDoc('ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作'),
       value: '字段当前值（只读）',
       record: '当前记录对象（只读，包含父记录全部字段值）',
       collection: '集合定义元数据（只读，描述字段所属集合的 Schema）',

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSItemRunJSContext extends FlowRunJSContext {}
 
 JSItemRunJSContext.define({
   label: 'JSItem RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for form item rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for form item rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     resource: `Current resource instance (read-only).
       Provides access to the data resource associated with the current form context.`,
     record: `Current record data object (read-only).
@@ -36,7 +37,7 @@ JSItemRunJSContext.define(
   {
     label: 'JS 表单项 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作',
+      element: createZhCNElementPropertyDoc('ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作'),
       resource: '当前资源（只读）',
       record: '当前记录（只读）',
       formValues: {