@nocobase/flow-engine 2.1.0-beta.9 → 2.2.0-alpha.1

package/src/flowI18n.ts

@@ -52,7 +52,8 @@ export class FlowI18n {
    */
   private translateKey(key: string, options?: any): string {
     if (this.context?.i18n?.t) {
-      return this.context.i18n.t(key, options);
+      const translated = this.context.i18n.t(key, options);
+      return translated == null || translated === '' ? key : translated;
     }
     // 如果没有翻译函数，返回原始键值
     return key;

package/src/flowSettings.ts

@@ -35,6 +35,7 @@ import {
 import { FlowExitAllException } from './utils/exceptions';
 import { FlowStepContext } from './hooks/useFlowStep';
 import { GLOBAL_EMBED_CONTAINER_ID, EMBED_REPLACING_DATA_KEY } from './views';
+import { lazy } from './lazy-helper';
 
 const Panel = Collapse.Panel;
 
@@ -114,16 +115,23 @@ export interface FlowSettingsOpenOptions {
   onSaved?: () => void | Promise<void>;
 }
 
+export type FlowSettingsComponent = React.ComponentType<any>;
+export type FlowSettingsComponentModule = { default?: FlowSettingsComponent } | Record<string, FlowSettingsComponent>;
+export type FlowSettingsComponentLoader = () => Promise<FlowSettingsComponentModule | FlowSettingsComponent>;
+export type FlowSettingsComponentLoaderMap = Record<string, FlowSettingsComponentLoader>;
+
 export class FlowSettings {
   public components: Record<string, any> = {};
   public scopes: Record<string, any> = {};
   private antdComponentsLoaded = false;
   public enabled: boolean;
+  private engine: FlowEngine;
   #forceEnabled = false; // 强制启用状态，主要用于设计模式下的强制启用
   public toolbarItems: ToolbarItemConfig[] = [];
   #emitter: Emitter = new Emitter();
 
   constructor(engine: FlowEngine) {
+    this.engine = engine;
     // 初始默认为 false，由 SchemaComponentProvider 根据实际设计模式状态同步设置
     this.enabled = false;
     engine.context.defineProperty('flowSettingsEnabled', {
@@ -291,6 +299,30 @@ export class FlowSettings {
     });
   }
 
+  public registerComponentLoaders(loaders: FlowSettingsComponentLoaderMap): void {
+    Object.entries(loaders).forEach(([name, loader]) => {
+      if (this.components[name]) {
+        console.warn(`FlowSettings: Component with name '${name}' is already registered and will be overwritten.`);
+      }
+      this.components[name] = lazy(async () => {
+        const loaded = await loader();
+        if (typeof loaded === 'function') {
+          return { default: loaded };
+        }
+        if (loaded?.default && typeof loaded.default === 'function') {
+          return { default: loaded.default };
+        }
+        const namedComponent = loaded?.[name];
+        if (typeof namedComponent === 'function') {
+          return { default: namedComponent };
+        }
+        throw new Error(
+          `FlowSettings: component loader for '${name}' must resolve to a React component or a module exporting it.`,
+        );
+      });
+    });
+  }
+
   /**
    * 添加作用域到 FlowSettings 的作用域注册表中。
    * 这些作用域可以在 flow step 的 uiSchema 中使用。
@@ -311,13 +343,15 @@ export class FlowSettings {
   /**
    * 启用流程设置组件的显示
    * @example
-   * flowSettings.enable();
+   * await flowSettings.enable();
    */
-  public enable(): void {
+  public async enable(): Promise<void> {
+    await this.engine.preloadModelLoaders();
     this.enabled = true;
   }
 
-  public forceEnable() {
+  public async forceEnable(): Promise<void> {
+    await this.engine.preloadModelLoaders();
     this.#forceEnabled = true;
     this.enabled = true;
   }
@@ -325,16 +359,16 @@ export class FlowSettings {
   /**
    * 禁用流程设置组件的显示
    * @example
-   * flowSettings.disable();
+   * await flowSettings.disable();
    */
-  public disable(): void {
+  public async disable(): Promise<void> {
     if (this.#forceEnabled) {
       return;
     }
     this.enabled = false;
   }
 
-  public forceDisable() {
+  public async forceDisable(): Promise<void> {
     this.#forceEnabled = false;
     this.enabled = false;
   }

package/src/index.ts

@@ -57,5 +57,7 @@ export {
 } from './views/viewEvents';
 
 export * from './FlowDefinition';
+export { DetachedFlowRegistry, replaceFlowRegistry, serializeFlowRegistry } from './flow-registry';
+export type { FlowRegistryData } from './flow-registry';
 export { createViewScopedEngine } from './ViewScopedFlowEngine';
 export { createBlockScopedEngine } from './BlockScopedFlowEngine';

package/src/lazy-helper.tsx

@@ -0,0 +1,57 @@
+/**
+ * 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 React, { lazy as reactLazy } from 'react';
+
+type LazyComponentType<M extends Record<string, any>, K extends keyof M> = {
+  [P in K]: M[P];
+};
+
+export function lazy<M extends Record<'default', any>>(factory: () => Promise<M>): M['default'];
+
+export function lazy<M extends Record<string, any>, K extends keyof M = keyof M>(
+  factory: () => Promise<M>,
+  ...componentNames: K[]
+): LazyComponentType<M, K>;
+
+export function lazy<M extends Record<string, any>, K extends keyof M>(
+  factory: () => Promise<M>,
+  ...componentNames: K[]
+) {
+  if (componentNames.length === 0) {
+    const LazyComponent = reactLazy(() =>
+      factory().then((module) => ({
+        default: module.default,
+      })),
+    );
+    const Component = (props) => (
+      <React.Suspense fallback={null}>
+        <LazyComponent {...props} />
+      </React.Suspense>
+    );
+    return Component;
+  }
+
+  return componentNames.reduce(
+    (acc, name) => {
+      const LazyComponent = reactLazy(() =>
+        factory().then((module) => ({
+          default: module[name],
+        })),
+      );
+      acc[name] = ((props) => (
+        <React.Suspense fallback={null}>
+          <LazyComponent {...props} />
+        </React.Suspense>
+      )) as M[K];
+      return acc;
+    },
+    {} as LazyComponentType<M, K>,
+  );
+}

package/src/locale/en-US.json

@@ -34,6 +34,7 @@
   "Failed to destroy model after creation error": "Failed to destroy model after creation error",
   "Failed to get action {{action}}": "Failed to get action {{action}}",
   "Failed to get configurable flows for model {{model}}": "Failed to get configurable flows for model {{model}}",
+  "Attributes are unavailable before selecting a record": "Attributes are unavailable before selecting a record",
   "Failed to import FormDialog": "Failed to import FormDialog",
   "Failed to import FormDialog or FormStep": "Failed to import FormDialog or FormStep",
   "Failed to import Formily components": "Failed to import Formily components",

package/src/locale/zh-CN.json

@@ -31,6 +31,7 @@
   "Failed to destroy model after creation error": "创建错误后销毁模型失败",
   "Failed to get action {{action}}": "获取 action '{{action}}' 失败",
   "Failed to get configurable flows for model {{model}}": "获取模型 '{{model}}' 的可配置 flows 失败",
+  "Attributes are unavailable before selecting a record": "选择记录之前，当前项属性不可用",
   "Failed to import FormDialog": "导入 FormDialog 失败",
   "Failed to import FormDialog or FormStep": "导入 FormDialog 或 FormStep 失败",
   "Failed to import Formily components": "导入 Formily 组件失败",

package/src/models/DisplayItemModel.tsx

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { DefaultStructure } from '@nocobase/flow-engine';
+import type { DefaultStructure } from '../types';
 import { CollectionFieldModel } from './CollectionFieldModel';
 
 export class DisplayItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

package/src/models/EditableItemModel.tsx

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { DefaultStructure } from '@nocobase/flow-engine';
+import type { DefaultStructure } from '../types';
 import { CollectionFieldModel } from './CollectionFieldModel';
 
 export class EditableItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

package/src/models/FilterableItemModel.tsx

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { DefaultStructure } from '@nocobase/flow-engine';
+import type { DefaultStructure } from '../types';
 import { CollectionFieldModel } from './CollectionFieldModel';
 
 export class FilterableItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

package/src/models/__tests__/flowEngine.resolveUse.test.ts

@@ -61,21 +61,6 @@ describe('FlowEngine.createModel resolveUse hook', () => {
     expect(warnSpy).not.toHaveBeenCalled();
   });
 
-  test('should break resolveUse on circular reference and warn', () => {
-    class LoopModel extends FlowModel {
-      static resolveUse() {
-        return 'LoopModel';
-      }
-    }
-
-    engine.registerModels({ LoopModel });
-
-    const model = engine.createModel({ use: 'LoopModel', uid: 'loop-model', flowEngine: engine });
-
-    expect(model).toBeInstanceOf(LoopModel);
-    expect(warnSpy).toHaveBeenCalled();
-  });
-
   test('should fall back to ErrorFlowModel when resolveUse returns unregistered name', () => {
     class MissingTargetEntry extends FlowModel {
       static resolveUse() {

package/src/models/__tests__/flowModel.test.ts

@@ -313,6 +313,19 @@ describe('FlowModel', () => {
 
         model.emitter.off('onStepParamsChanged', listener);
       });
+
+      test('should not emit onStepParamsChanged when params are unchanged', () => {
+        const listener = vi.fn();
+        model.emitter.on('onStepParamsChanged', listener);
+
+        model.setStepParams('testFlow', 'step1', { param1: 'value1' });
+        model.setStepParams('testFlow', { step1: { param1: 'value1' } });
+        model.setStepParams({ testFlow: { step1: { param1: 'value1' } } });
+
+        expect(listener).not.toHaveBeenCalled();
+
+        model.emitter.off('onStepParamsChanged', listener);
+      });
     });
   });
 
@@ -370,15 +383,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        const result = await model.applyFlow('exitFlow');
-
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should handle ctx.exit() as FlowExitAllException in beforeRender dispatch', async () => {
@@ -474,15 +489,17 @@ describe('FlowModel', () => {
         };
 
         TestFlowModel.registerFlow(exitFlow);
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-
-        const result = await model.applyFlow('exitFlow');
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
-        expect(result).toBeInstanceOf(FlowExitAllException);
-        expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
-        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        try {
+          const result = await model.applyFlow('exitFlow');
 
-        consoleSpy.mockRestore();
+          expect(result).toBeInstanceOf(FlowExitAllException);
+          expect(exitFlow.steps.step2.handler).not.toHaveBeenCalled();
+          expect(loggerSpy).toHaveBeenCalledWith(expect.stringContaining('[FlowModel]'));
+        } finally {
+          loggerSpy.mockRestore();
+        }
       });
 
       test('should propagate step execution errors', async () => {
@@ -768,7 +785,7 @@ describe('FlowModel', () => {
         const eventFlow = createEventFlowDefinition('testEvent');
         TestFlowModel.registerFlow(eventFlow);
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.dispatchEvent('testEvent', { data: 'payload' });
@@ -776,7 +793,7 @@ describe('FlowModel', () => {
           // Use a more reliable approach than arbitrary timeout
           await new Promise((resolve) => setTimeout(resolve, 0));
 
-          expect(consoleSpy).toHaveBeenCalledWith(
+          expect(loggerSpy).toHaveBeenCalledWith(
             expect.stringContaining('[FlowModel] dispatchEvent: uid=test-model-uid, event=testEvent'),
           );
           expect(eventFlow.steps.eventStep.handler).toHaveBeenCalledWith(
@@ -786,7 +803,7 @@ describe('FlowModel', () => {
             expect.any(Object),
           );
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
@@ -1597,7 +1614,7 @@ describe('FlowModel', () => {
         fork1.dispose = vi.fn();
         fork2.dispose = vi.fn();
 
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
@@ -1606,19 +1623,19 @@ describe('FlowModel', () => {
           expect(fork2.dispose).toHaveBeenCalled();
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
 
       test('should handle empty forks collection when clearing', () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         try {
           model.clearForks();
 
           expect(model.forks.size).toBe(0);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1746,7 +1763,7 @@ describe('FlowModel', () => {
       test('should clean up resources on remove', () => {
         model.createFork();
         model.createFork();
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
         // Mock removeModel to simulate proper fork cleanup
         flowEngine.removeModel = vi.fn().mockImplementation(() => {
@@ -1763,7 +1780,7 @@ describe('FlowModel', () => {
           expect(model.forks.size).toBe(0);
           expect(flowEngine.removeModel).toHaveBeenCalledWith(model.uid);
         } finally {
-          consoleSpy.mockRestore();
+          loggerSpy.mockRestore();
         }
       });
     });
@@ -1840,22 +1857,17 @@ describe('FlowModel', () => {
       });
 
       test('should rerender triggers beforeRender without cache', async () => {
-        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
         model.dispatchEvent = vi.fn().mockResolvedValue(undefined) as any;
 
-        try {
-          await expect(model.rerender()).resolves.not.toThrow();
-          expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
-            useCache: false,
-          });
-        } finally {
-          consoleSpy.mockRestore();
-        }
+        await expect(model.rerender()).resolves.not.toThrow();
+        expect(model.dispatchEvent).toHaveBeenCalledWith('beforeRender', undefined, {
+          useCache: false,
+        });
       });
     });
 
     describe('serialization', () => {
-      test('should serialize basic model data, excluding props and flowEngine', () => {
+      test('should serialize basic model data with the latest props, excluding flowEngine', () => {
         model.sortIndex = 5;
         model.setProps({ name: 'Test Model', value: 42 });
         model.setStepParams({
@@ -1867,13 +1879,12 @@ describe('FlowModel', () => {
         expect(serialized).toEqual(
           expect.objectContaining({
             uid: model.uid,
+            props: expect.objectContaining({ name: 'Test Model', value: 42 }),
             stepParams: expect.objectContaining({ flow1: { step1: { param1: 'value1' } } }),
             sortIndex: 5,
             subModels: expect.any(Object),
           }),
         );
-        // props should be excluded from serialization
-        expect(serialized.props).toBeUndefined();
         expect(serialized.flowEngine).toBeUndefined();
       });
 
@@ -1892,6 +1903,7 @@ describe('FlowModel', () => {
         expect(serialized).toEqual(
           expect.objectContaining({
             uid: 'empty-model',
+            props: expect.objectContaining({ foo: 'bar' }),
             stepParams: expect.any(Object),
             sortIndex: expect.any(Number),
             subModels: expect.any(Object),
@@ -1899,6 +1911,22 @@ describe('FlowModel', () => {
         );
         expect(serialized.flowEngine).toBeUndefined();
       });
+
+      test('should serialize the latest props after multiple updates', () => {
+        model.setProps({ fieldNames: { title: 'name' }, searchable: true });
+        model.setProps({ fieldNames: { title: 'age' } });
+        model.setProps('defaultExpandAll', false);
+
+        const serialized = model.serialize();
+
+        expect(serialized.props).toEqual(
+          expect.objectContaining({
+            fieldNames: { title: 'age' },
+            searchable: true,
+            defaultExpandAll: false,
+          }),
+        );
+      });
     });
   });
 
@@ -2874,7 +2902,7 @@ describe('FlowModel', () => {
   describe('Edge Cases & Error Handling', () => {
     test('should handle model destruction gracefully', () => {
       const model = new FlowModel(modelOptions);
-      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const loggerSpy = vi.spyOn(model.flowEngine.logger, 'debug').mockImplementation(() => {});
 
       model.createFork();
       model.setProps({ testProp: 'value' });
@@ -2882,7 +2910,7 @@ describe('FlowModel', () => {
       try {
         expect(() => model.remove()).not.toThrow();
       } finally {
-        consoleSpy.mockRestore();
+        loggerSpy.mockRestore();
       }
     });