@nocobase/flow-engine 2.0.0-alpha.2

package/src/models/CollectionFieldModel.tsx

@@ -0,0 +1,269 @@
+/**
+ * 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 { Card, Form } from 'antd';
+import _ from 'lodash';
+import React from 'react';
+import { CollectionField } from '../data-source';
+import { FlowEngineContext } from '../flowContext';
+import { DefaultStructure } from '../types';
+import { escapeT } from '../utils';
+import { FlowModel } from './flowModel';
+
+export function FieldPlaceholder() {
+  return (
+    <Form.Item>
+      <Card
+        size="small"
+        styles={{
+          body: {
+            color: 'rgba(0,0,0,0.45)',
+          },
+        }}
+      >
+        该字段已被隐藏，你无法查看（该内容仅在激活 UI Editor 时显示）。
+      </Card>
+    </Form.Item>
+  );
+}
+
+export interface FieldSettingsInitParams {
+  dataSourceKey: string;
+  collectionName: string;
+  fieldPath: string;
+  associationPathName?: string;
+}
+
+export interface BindingOptions {
+  modelName: string;
+  isDefault: boolean;
+  defaultProps: object | ((ctx: FlowEngineContext, fieldInstance: CollectionField) => object) | null;
+  when: (ctx: FlowEngineContext, fieldInstance: CollectionField) => boolean;
+}
+
+const defaultWhen = () => true;
+
+export class CollectionFieldModel<T extends DefaultStructure = DefaultStructure> extends FlowModel<T> {
+  private static _bindings = new Map();
+
+  renderHiddenInConfig(): React.ReactNode | undefined {
+    return <FieldPlaceholder />;
+  }
+
+  get title() {
+    return undefined;
+  }
+
+  onInit(options: any): void {
+    this.context.defineProperty('collectionField', {
+      get: () => {
+        const params = this.getFieldSettingsInitParams();
+        const collectionField = this.context.dataSourceManager.getCollectionField(
+          `${params.dataSourceKey}.${params.collectionName}.${params.fieldPath}`,
+        ) as CollectionField;
+        return collectionField;
+      },
+      cache: false,
+    });
+    this.context.defineProperty('fieldPath', {
+      get: () => {
+        return this.fieldPath;
+      },
+    });
+    this.context.blockModel.addAppends(this.fieldPath);
+    this.context.blockModel.addAppends(this.associationPathName);
+  }
+
+  getFieldSettingsInitParams(): FieldSettingsInitParams {
+    return this.getStepParams('fieldSettings', 'init');
+  }
+
+  get fieldPath(): string {
+    return this.getFieldSettingsInitParams().fieldPath;
+  }
+
+  get associationPathName(): string {
+    return this.getFieldSettingsInitParams().associationPathName;
+  }
+
+  get collectionField() {
+    return this.context.collectionField as CollectionField;
+  }
+
+  async afterAddAsSubModel() {
+    if (this.context.resource) {
+      await this.context.resource.refresh();
+    }
+  }
+
+  static getBindingsByField(ctx: FlowEngineContext, collectionField: CollectionField): BindingOptions[] {
+    const interfaceName = collectionField.interface;
+
+    // Check if the interface exists in the map
+    if (!this.bindings.has(interfaceName)) {
+      return [];
+    }
+
+    // Filter the mappings based on the `when` condition
+    const bindings = this.bindings.get(interfaceName);
+    return bindings.filter(
+      (binding) => ctx.engine.getModelClass(binding.modelName) && binding.when(ctx, collectionField),
+    );
+  }
+
+  static getDefaultBindingByField(
+    ctx: FlowEngineContext,
+    collectionField: CollectionField,
+    options: { useStrict?: boolean; fallbackToTargetTitleField?: boolean } = {},
+  ): BindingOptions | null {
+    if (options.fallbackToTargetTitleField) {
+      const binding = this.getDefaultBindingByField(ctx, collectionField, { useStrict: true });
+      if (!binding) {
+        if (collectionField.isAssociationField() && collectionField.targetCollectionTitleField) {
+          return this.getDefaultBindingByField(ctx, collectionField.targetCollectionTitleField);
+        }
+      }
+      return binding;
+    }
+    const interfaceName = collectionField.interface;
+    if (!interfaceName) {
+      return null;
+    }
+    // Check if the interface exists in the map
+    if (!this.bindings.has(interfaceName)) {
+      return null;
+    }
+    // Find the default mapping
+    const bindings = this.bindings.get(interfaceName);
+    const defaultBindings = bindings.filter(
+      (binding) =>
+        binding.isDefault && ctx.engine.getModelClass(binding.modelName) && binding.when(ctx, collectionField),
+    );
+    if (defaultBindings.length === 1) {
+      return defaultBindings[0];
+    }
+    if (defaultBindings.length > 0) {
+      let defaultBinding = null;
+      defaultBinding = defaultBindings.find((binding) => binding.when !== defaultWhen);
+      if (defaultBinding) {
+        return defaultBinding;
+      }
+      defaultBinding = defaultBindings.find((binding) => binding.when === defaultWhen);
+      if (defaultBinding) {
+        return defaultBinding;
+      }
+    }
+    if (options.useStrict) {
+      return null;
+    }
+    return bindings.find(
+      (binding) => ctx.engine.getModelClass(binding.modelName) && binding.when(ctx, collectionField),
+    );
+  }
+
+  static bindModelToInterface(
+    modelName: string,
+    interfaceName: string | string[],
+    options: {
+      isDefault?: boolean;
+      defaultProps?: object | ((ctx: FlowEngineContext, fieldInstance: CollectionField) => object);
+      when?: (ctx: FlowEngineContext, fieldInstance: CollectionField) => boolean;
+    } = {},
+  ) {
+    if (Array.isArray(interfaceName)) {
+      interfaceName.forEach((name) => this.bindModelToInterface(modelName, name, options));
+      return;
+    }
+    // Ensure the interface entry exists in the map
+    if (!this.currentBindings.has(interfaceName)) {
+      this.currentBindings.set(interfaceName, []);
+    }
+
+    // Add the mapping entry
+    const bindings = this.currentBindings.get(interfaceName);
+    bindings.push({
+      modelName,
+      isDefault: options.isDefault || false,
+      defaultProps: options.defaultProps || null,
+      when: options.when || defaultWhen,
+    });
+
+    // Update the map
+    this.currentBindings.set(interfaceName, bindings);
+  }
+
+  private static get currentBindings() {
+    if (!Object.prototype.hasOwnProperty.call(this, '_bindings') || !this._bindings) {
+      this._bindings = new Map();
+    }
+    return this._bindings;
+  }
+
+  static getAllParentClasses(): any[] {
+    const parentClasses = [];
+    let currentClass: any = this;
+
+    while (currentClass && currentClass !== Object) {
+      currentClass = Object.getPrototypeOf(currentClass);
+      if (currentClass?.currentBindings) {
+        parentClasses.push(currentClass);
+      }
+    }
+
+    return parentClasses;
+  }
+
+  static get bindings() {
+    const allBindings = new Map();
+
+    // 获取当前类及其所有父类
+    const allParentClasses = this.getAllParentClasses();
+
+    // 遍历所有父类的绑定
+    for (const parentClass of allParentClasses) {
+      for (const [interfaceName, binding] of parentClass.currentBindings) {
+        if (!allBindings.has(interfaceName)) {
+          allBindings.set(interfaceName, []);
+        }
+        allBindings.get(interfaceName).unshift(...binding);
+      }
+    }
+
+    // 合并当前类的绑定
+    for (const [interfaceName, binding] of this.currentBindings) {
+      if (!allBindings.has(interfaceName)) {
+        allBindings.set(interfaceName, []);
+      }
+      allBindings.get(interfaceName).unshift(...binding);
+    }
+
+    return allBindings;
+  }
+}
+
+CollectionFieldModel.registerFlow({
+  key: 'fieldSettings',
+  title: escapeT('Field settings'),
+  steps: {
+    init: {
+      handler(ctx, params) {
+        const { dataSourceKey, collectionName, fieldPath } = params;
+        if (!dataSourceKey) {
+          throw new Error('dataSourceKey is a required parameter');
+        }
+        if (!collectionName) {
+          throw new Error('collectionName is a required parameter');
+        }
+        if (!fieldPath) {
+          throw new Error('fieldPath is a required parameter');
+        }
+      },
+    },
+  },
+});

package/src/models/DisplayItemModel.tsx

@@ -0,0 +1,13 @@
+/**
+ * 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 { DefaultStructure } from '@nocobase/flow-engine';
+import { CollectionFieldModel } from './CollectionFieldModel';
+
+export class DisplayItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

package/src/models/EditableItemModel.tsx

@@ -0,0 +1,13 @@
+/**
+ * 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 { DefaultStructure } from '@nocobase/flow-engine';
+import { CollectionFieldModel } from './CollectionFieldModel';
+
+export class EditableItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

package/src/models/FilterableItemModel.tsx

@@ -0,0 +1,13 @@
+/**
+ * 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 { DefaultStructure } from '@nocobase/flow-engine';
+import { CollectionFieldModel } from './CollectionFieldModel';
+
+export class FilterableItemModel<T extends DefaultStructure = DefaultStructure> extends CollectionFieldModel<T> {}

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

@@ -0,0 +1,122 @@
+/**
+ * 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 { CollectionFieldModel } from '@nocobase/flow-engine';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+describe('CollectionFieldModel', () => {
+  let mockContext: any;
+  let mockCollectionField: any;
+
+  let TestModel: typeof CollectionFieldModel;
+
+  beforeEach(() => {
+    // @ts-ignore
+    TestModel = class extends CollectionFieldModel {};
+    // Mock context and collectionField
+    mockContext = {
+      engine: {
+        getModelClass: (modelName: string) => modelName === 'ValidModel', // Only 'ValidModel' is valid
+      },
+    };
+
+    mockCollectionField = {
+      interface: 'TestInterface',
+      target: 'test',
+    };
+
+    // Clear bindings before each test
+    TestModel.bindings.clear();
+  });
+
+  it('should bind a model to an interface', () => {
+    TestModel.bindModelToInterface('TestModel', 'TestInterface', {
+      isDefault: true,
+      when: (ctx, field) => field.target === 'test',
+    });
+
+    const bindings = TestModel.bindings.get('TestInterface');
+    expect(bindings).toHaveLength(1);
+    expect(bindings[0]).toMatchObject({
+      modelName: 'TestModel',
+      isDefault: true,
+    });
+  });
+
+  it('should get bindings by field', () => {
+    TestModel.bindModelToInterface('ValidModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'test',
+    });
+    TestModel.bindModelToInterface('InvalidModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'invalid',
+    });
+
+    const bindings = TestModel.getBindingsByField(mockContext, mockCollectionField);
+    expect(bindings).toHaveLength(1);
+    expect(bindings[0].modelName).toBe('ValidModel');
+  });
+
+  it('should get default binding by field', () => {
+    TestModel.bindModelToInterface('ValidModel', 'TestInterface', {
+      isDefault: true,
+      when: (ctx, field) => field.target === 'test',
+    });
+    TestModel.bindModelToInterface('AnotherModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'test',
+    });
+
+    const defaultBinding = TestModel.getDefaultBindingByField(mockContext, mockCollectionField);
+    expect(defaultBinding).toBeTruthy();
+    expect(defaultBinding.modelName).toBe('ValidModel');
+  });
+
+  it('should get default binding by field', () => {
+    TestModel.bindModelToInterface('ValidModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'test',
+    });
+    TestModel.bindModelToInterface('AnotherModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'test',
+    });
+
+    const defaultBinding = TestModel.getDefaultBindingByField(mockContext, mockCollectionField);
+    expect(defaultBinding).toBeTruthy();
+    expect(defaultBinding.modelName).toBe('ValidModel');
+  });
+
+  it('should return null if no default binding is found', () => {
+    TestModel.bindModelToInterface('AnotherModel', 'TestInterface', {
+      when: (ctx, field) => field.target === 'test',
+    });
+
+    const defaultBinding = TestModel.getDefaultBindingByField(mockContext, mockCollectionField);
+    expect(defaultBinding).toBeFalsy();
+  });
+
+  it('should return an empty array if no bindings are found', () => {
+    const bindings = TestModel.getBindingsByField(mockContext, mockCollectionField);
+    expect(bindings).toHaveLength(0);
+  });
+
+  it('should return null if no bindings exist for the interface', () => {
+    const defaultBinding = TestModel.getDefaultBindingByField(mockContext, mockCollectionField);
+    expect(defaultBinding).toBeNull();
+  });
+
+  it('should return null if no bindings exist for the interface', () => {
+    class Test1Model extends CollectionFieldModel {}
+    class Test2Model extends Test1Model {}
+    class Test3Model extends Test1Model {}
+    Test1Model.bindModelToInterface('TestModel1', 'TestInterface');
+    Test2Model.bindModelToInterface('TestModel2', 'TestInterface');
+    Test3Model.bindModelToInterface('TestModel3', 'TestInterface');
+    expect(Test1Model.bindings.get('TestInterface')).toHaveLength(1);
+    expect(Test2Model.bindings.get('TestInterface')).toHaveLength(2);
+    expect(Test3Model.bindings.get('TestInterface')).toHaveLength(2);
+  });
+});

package/src/models/__tests__/defaultParams-on-create.test.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { defineFlow, FlowModel } from '../flowModel';
+
+describe('FlowDefinition.defaultParams applied at createModel', () => {
+  it('fills missing stepParams on createModel', async () => {
+    class ModelA extends FlowModel {}
+    ModelA.registerFlow(
+      defineFlow({
+        key: 'alpha',
+        steps: { s1: {} },
+        defaultParams: () => ({ s1: { a: 1 } }),
+      }),
+    );
+
+    const engine = new FlowEngine();
+    engine.registerModels({ ModelA });
+    const m = engine.createModel<ModelA>({ use: 'ModelA', uid: 'm-alpha' });
+
+    await waitFor(() => {
+      expect(m.getStepParams('alpha', 's1')).toEqual({ a: 1 });
+    });
+  });
+
+  it('does not override existing stepParams', async () => {
+    class ModelB extends FlowModel {}
+    ModelB.registerFlow(
+      defineFlow({
+        key: 'alpha',
+        steps: { s1: {} },
+        defaultParams: () => ({ s1: { a: 1 } }),
+      }),
+    );
+
+    const engine = new FlowEngine();
+    engine.registerModels({ ModelB });
+    const m = engine.createModel<ModelB>({
+      use: 'ModelB',
+      uid: 'm-beta',
+      stepParams: { alpha: { s1: { a: 42 } } },
+    });
+
+    await waitFor(() => {
+      expect(m.getStepParams('alpha', 's1')).toEqual({ a: 42 });
+    });
+  });
+
+  // only step-level shape is supported; flowKey wrapping is not needed
+
+  it('partially fills only missing steps', async () => {
+    class ModelD extends FlowModel {}
+    ModelD.registerFlow(
+      defineFlow({
+        key: 'theta',
+        steps: { s1: {}, s2: {} },
+        defaultParams: () => ({ s1: { a: 1 }, s2: { b: 2 } }),
+      }),
+    );
+
+    const engine = new FlowEngine();
+    engine.registerModels({ ModelD });
+    const m = engine.createModel<ModelD>({
+      use: 'ModelD',
+      uid: 'm-theta',
+      stepParams: { theta: { s1: { a: 99 } } },
+    });
+
+    await waitFor(() => {
+      expect(m.getStepParams('theta', 's1')).toEqual({ a: 99 }); // unchanged
+      expect(m.getStepParams('theta', 's2')).toEqual({ b: 2 }); // filled
+    });
+  });
+});

package/src/models/__tests__/flow-model-oninit.test.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../flowModel';
+
+describe('FlowModel.onInit', () => {
+  it('calls parent onInit before children onInit', () => {
+    const order: string[] = [];
+
+    class A extends FlowModel {
+      onInit(options: any): void {
+        super.onInit(options);
+        order.push('A');
+      }
+    }
+
+    class B extends FlowModel {
+      onInit(options: any): void {
+        super.onInit(options);
+        order.push('B');
+      }
+    }
+
+    const engine = new FlowEngine();
+    engine.registerModels({ A, B });
+
+    engine.createModel({
+      use: 'A',
+      subModels: {
+        b1: [{ use: 'B' }, { use: 'B' }],
+      },
+    });
+
+    expect(order).toEqual(['A', 'B', 'B']);
+  });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * 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 { describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../flowModel';
+
+describe('FlowModel + Engine actions integration', () => {
+  it('merges engine global actions and class-level actions', () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const g = vi.fn();
+    const c = vi.fn();
+    engine.registerActions({ g: { name: 'g', handler: g } });
+    M.registerAction({ name: 'c', handler: c });
+
+    const m = engine.createModel<M>({ use: 'M' });
+    const map = m.getActions();
+    expect(map.has('g')).toBe(true);
+    expect(map.has('c')).toBe(true);
+  });
+
+  it('class-level overrides engine action with same name', () => {
+    const engine = new FlowEngine();
+    class X extends FlowModel {}
+    engine.registerModels({ X });
+
+    const g = vi.fn();
+    const c = vi.fn();
+    engine.registerActions({ dup: { name: 'dup', handler: g } });
+    X.registerAction({ name: 'dup', handler: c });
+
+    const m = engine.createModel<X>({ use: 'X' });
+    expect(m.getAction('dup')?.handler).toBe(c);
+  });
+
+  it('long inheritance chain picks up ancestor updates on next call', () => {
+    const engine = new FlowEngine();
+    class A extends FlowModel {}
+    class B extends A {}
+    class C extends B {}
+    class D extends C {}
+    class E extends D {}
+    engine.registerModels({ A, B, C, D, E });
+
+    const model = engine.createModel<E>({ use: 'E' });
+    // warm
+    model.getActions();
+
+    const handler = vi.fn();
+    A.registerAction({ name: 'ancestor', handler });
+
+    const map = model.getActions();
+    expect(map.has('ancestor')).toBe(true);
+  });
+
+  it('engine actions added after model creation are immediately visible', () => {
+    const engine = new FlowEngine();
+    class N extends FlowModel {}
+    engine.registerModels({ N });
+    const m = engine.createModel<N>({ use: 'N' });
+    // Initially empty
+    expect(m.getActions().has('g2')).toBe(false);
+    engine.registerActions({ g2: { name: 'g2', handler: () => {} } });
+    // Immediately visible without any invalidation call
+    expect(m.getActions().has('g2')).toBe(true);
+  });
+
+  it('getAction falls back to engine when not defined in class chain', () => {
+    const engine = new FlowEngine();
+    class Q extends FlowModel {}
+    engine.registerModels({ Q });
+    const g = () => {};
+    engine.registerActions({ onlyG: { name: 'onlyG', handler: g } });
+    const m = engine.createModel<Q>({ use: 'Q' });
+    expect(m.getAction('onlyG')?.handler).toBe(g);
+  });
+
+  it('mutating returned map from getActions (deleting key) does not affect internal registries', () => {
+    const engine = new FlowEngine();
+    class Z extends FlowModel {}
+    engine.registerModels({ Z });
+    const h = () => {};
+    Z.registerAction({ name: 'zAct', handler: h });
+    const m = engine.createModel<Z>({ use: 'Z' });
+    const map = m.getActions();
+    // delete existing key from the returned map copy
+    map.delete('zAct');
+    // Internal registries are not polluted
+    expect(m.getAction('zAct')?.handler).toBe(h);
+  });
+});