@nocobase/flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.11

package/src/__tests__/flowSettings.test.ts

@@ -8,6 +8,10 @@
  */
 
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import React from 'react';
+import { createForm } from '@formily/core';
+import { createSchemaField, FormProvider } from '@formily/react';
+import { render, screen } from '@testing-library/react';
 import { FlowSettings } from '../flowSettings';
 import { DefaultSettingsIcon } from '../components/settings/wrappers/contextual/DefaultSettingsIcon';
 import { FlowModel } from '../models';
@@ -142,10 +146,10 @@ describe('FlowSettings', () => {
       expect(settingsItem?.sort).toBe(0);
     });
 
-    test('should set up observable properties', () => {
+    test('should set up observable properties', async () => {
       // Test that enabled property is reactive
       const initialEnabled = flowSettings.enabled;
-      flowSettings.enable();
+      await flowSettings.enable();
       expect(flowSettings.enabled).not.toBe(initialEnabled);
       expect(flowSettings.enabled).toBe(true);
     });
@@ -186,6 +190,43 @@ describe('FlowSettings', () => {
       flowSettings.registerComponents({});
       expect(Object.keys(flowSettings.components)).toHaveLength(0);
     });
+
+    test('should register component loaders and load component on render', async () => {
+      const loader = vi.fn(async () => ({
+        default: () => React.createElement('div', null, 'Lazy Flow Settings Component'),
+      }));
+
+      flowSettings.registerComponentLoaders({
+        DemoFlowSettingsLazyField: loader,
+      });
+
+      expect(loader).not.toHaveBeenCalled();
+
+      const SchemaField = createSchemaField();
+      const form = createForm();
+
+      render(
+        React.createElement(
+          FormProvider,
+          { form },
+          React.createElement(SchemaField, {
+            schema: {
+              type: 'object',
+              properties: {
+                demo: {
+                  type: 'void',
+                  'x-component': 'DemoFlowSettingsLazyField',
+                },
+              },
+            },
+            components: flowSettings.components,
+          }),
+        ),
+      );
+
+      expect(await screen.findByText('Lazy Flow Settings Component')).toBeInTheDocument();
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe('Scope Registration', () => {
@@ -228,30 +269,68 @@ describe('FlowSettings', () => {
   });
 
   describe('Enable/Disable Functionality', () => {
-    test('should enable flow settings', () => {
+    test('should enable flow settings', async () => {
       expect(flowSettings.enabled).toBe(false);
 
-      flowSettings.enable();
+      await flowSettings.enable();
 
       expect(flowSettings.enabled).toBe(true);
     });
 
-    test('should disable flow settings', () => {
-      flowSettings.enable();
+    test('should preload model loaders before enabling flow settings', async () => {
+      const preloadSpy = vi.spyOn(engine, 'preloadModelLoaders').mockResolvedValue({
+        requested: [],
+        loaded: [],
+        failed: [],
+      });
+
+      await flowSettings.enable();
+
+      expect(preloadSpy).toHaveBeenCalledTimes(1);
       expect(flowSettings.enabled).toBe(true);
+    });
 
-      flowSettings.disable();
+    test('should preload model loaders before force enabling flow settings', async () => {
+      const preloadSpy = vi.spyOn(engine, 'preloadModelLoaders').mockResolvedValue({
+        requested: [],
+        loaded: [],
+        failed: [],
+      });
+
+      await flowSettings.forceEnable();
+
+      expect(preloadSpy).toHaveBeenCalledTimes(1);
+      expect(flowSettings.enabled).toBe(true);
+    });
+
+    test('should disable flow settings', async () => {
+      await flowSettings.enable();
+      expect(flowSettings.enabled).toBe(true);
+
+      await flowSettings.disable();
 
       expect(flowSettings.enabled).toBe(false);
     });
 
-    test('should handle multiple enable/disable calls', () => {
-      flowSettings.enable();
-      flowSettings.enable();
+    test('should handle multiple enable/disable calls', async () => {
+      await flowSettings.enable();
+      await flowSettings.enable();
       expect(flowSettings.enabled).toBe(true);
 
-      flowSettings.disable();
-      flowSettings.disable();
+      await flowSettings.disable();
+      await flowSettings.disable();
+      expect(flowSettings.enabled).toBe(false);
+    });
+
+    test('forceDisable should clear force-enabled state and disable flow settings', async () => {
+      await flowSettings.forceEnable();
+      expect(flowSettings.enabled).toBe(true);
+
+      await flowSettings.forceDisable();
+
+      expect(flowSettings.enabled).toBe(false);
+
+      await flowSettings.disable();
       expect(flowSettings.enabled).toBe(false);
     });
   });
@@ -512,7 +591,7 @@ describe('FlowSettings', () => {
   });
 
   describe('Complex Integration Scenarios', () => {
-    test('should maintain state consistency during multiple operations', () => {
+    test('should maintain state consistency during multiple operations', async () => {
       // Initialize with components and scopes
       const TestComponent = () => 'TestComponent';
       const testScope = () => 'testScope';
@@ -528,7 +607,7 @@ describe('FlowSettings', () => {
       });
 
       // Enable/disable
-      flowSettings.enable();
+      await flowSettings.enable();
       expect(flowSettings.enabled).toBe(true);
 
       // Verify all state is maintained
@@ -536,7 +615,7 @@ describe('FlowSettings', () => {
       expect(flowSettings.scopes.testScope).toBe(testScope);
       expect(flowSettings.getToolbarItems().find((item) => item.key === 'integration-test')).toBeDefined();
 
-      flowSettings.disable();
+      await flowSettings.disable();
       expect(flowSettings.enabled).toBe(false);
 
       // State should still be maintained after disable

package/src/__tests__/provider.test.tsx

@@ -14,11 +14,6 @@ import { FlowEngine } from '../flowEngine';
 import { FlowEngineProvider, useFlowEngine } from '../provider';
 
 describe('FlowEngineProvider/useFlowEngine', () => {
-  it('throws without provider', () => {
-    const run = () => renderHook(() => useFlowEngine());
-    expect(run).toThrow(/FlowEngineProvider/);
-  });
-
   it('returns engine within provider', () => {
     const engine = new FlowEngine();
     const wrapper = ({ children }: any) => <FlowEngineProvider engine={engine}>{children}</FlowEngineProvider>;

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

@@ -7,17 +7,17 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import {
   RunJSContextRegistry,
-  getRunJSDocFor,
   createJSRunnerWithVersion,
-  getRunJSScenesForModel,
+  getRunJSDocFor,
   getRunJSScenesForContext,
+  getRunJSScenesForModel,
 } from '..';
-import { setupRunJSContexts } from '../runjs-context/setup';
 import { FlowContext } from '../flowContext';
 import { JSRunner } from '../JSRunner';
+import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('flowRunJSContext registry and doc', () => {
   beforeAll(async () => {
@@ -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 () => {
@@ -80,7 +95,10 @@ describe('flowRunJSContext registry and doc', () => {
       (ctx as any).defineProperty('model', { value: { constructor: { name: 'JSFieldModel' } } });
       (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
-      expect(doc?.properties?.message).toMatch(/Ant Design 全局消息/);
+      const message = doc?.properties?.message;
+      const messageText =
+        typeof message === 'string' ? message : (message as any)?.description ?? (message as any)?.detail ?? '';
+      expect(String(messageText)).toMatch(/Ant Design 全局消息/);
     });
 
     it('should fallback to English when locale is not found', () => {
@@ -172,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', () => {
@@ -208,10 +227,10 @@ describe('flowRunJSContext registry and doc', () => {
       expect(doc?.properties?.message).toBeTruthy();
     });
 
-    it('should have api property in base context', () => {
+    it('should have request method in base context', () => {
       const ctx: any = { model: { constructor: { name: '*' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
-      expect(doc?.properties?.api).toBeTruthy();
+      expect(doc?.methods?.request).toBeTruthy();
     });
 
     it('should have t method in base context', () => {

package/src/__tests__/runjsContextImplementations.test.ts

@@ -7,10 +7,10 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { RunJSContextRegistry, getRunJSDocFor } from '..';
-import { setupRunJSContexts } from '../runjs-context/setup';
 import { FlowContext } from '../flowContext';
+import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('Specific RunJSContext implementations', () => {
   beforeAll(async () => {
@@ -34,7 +34,8 @@ describe('Specific RunJSContext implementations', () => {
       const ctx: any = { model: { constructor: { name: 'JSColumnModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.properties?.record).toBeTruthy();
-      expect(doc?.properties?.record).toContain('row record');
+      const recordDoc: any = doc?.properties?.record;
+      expect(String(recordDoc?.description ?? recordDoc ?? '')).toContain('row record');
     });
 
     it('should have recordIndex property in doc', () => {
@@ -86,6 +87,14 @@ describe('Specific RunJSContext implementations', () => {
       expect(doc?.properties?.antd).toBeTruthy();
     });
 
+    it('should have ctx.auth.locale / ctx.viewer.drawer in doc', () => {
+      const ctx: any = { model: { constructor: { name: 'JSBlockModel' } } };
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+
+      expect(doc?.properties?.auth?.properties?.locale).toBeTruthy();
+      expect(doc?.properties?.viewer?.properties?.drawer).toBeTruthy();
+    });
+
     it('should have element property', () => {
       const ctx: any = { model: { constructor: { name: 'JSBlockModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
@@ -214,4 +223,26 @@ describe('Specific RunJSContext implementations', () => {
       expect(doc?.label).toMatch(/表单 JS 字段项/);
     });
   });
+
+  describe('JSEditableFieldRunJSContext', () => {
+    it('should be registered for JSEditableFieldModel', () => {
+      const ctor = RunJSContextRegistry['resolve']('v1' as any, 'JSEditableFieldModel');
+      expect(ctor).toBeTruthy();
+    });
+
+    it('should have getValue/setValue methods in doc', () => {
+      const ctx: any = { model: { constructor: { name: 'JSEditableFieldModel' } } };
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+      expect(doc?.methods?.getValue).toBeTruthy();
+      expect(doc?.methods?.setValue).toBeTruthy();
+    });
+
+    it('should support zh-CN locale', () => {
+      const ctx = new FlowContext();
+      (ctx as any).defineProperty('model', { value: { constructor: { name: 'JSEditableFieldModel' } } });
+      (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+      expect(doc?.label).toMatch(/可编辑字段/);
+    });
+  });
 });

package/src/__tests__/runjsContextRuntime.test.ts

@@ -7,9 +7,9 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { describe, it, expect, beforeAll } from 'vitest';
-import { FlowContext } from '../flowContext';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { createJSRunnerWithVersion, getRunJSDocFor } from '..';
+import { FlowContext } from '../flowContext';
 import { setupRunJSContexts } from '../runjs-context/setup';
 
 describe('RunJS Context Runtime Behavior', () => {
@@ -186,6 +186,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',
@@ -224,7 +225,7 @@ describe('RunJS Context Runtime Behavior', () => {
         // Base properties from FlowRunJSContext
         expect(doc?.properties?.logger).toBeTruthy();
         expect(doc?.properties?.message).toBeTruthy();
-        expect(doc?.properties?.api).toBeTruthy();
+        expect(doc?.methods?.request).toBeTruthy();
         expect(doc?.methods?.t).toBeTruthy();
         expect(doc?.methods?.requireAsync).toBeTruthy();
       }
@@ -237,6 +238,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',

package/src/__tests__/runjsContributions.test.ts

@@ -0,0 +1,89 @@
+/**
+ * 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, it, expect, vi } from 'vitest';
+
+describe('RunJS context contributions', () => {
+  it('should apply contribution during setupRunJSContexts()', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const {
+      registerRunJSContextContribution,
+      setupRunJSContexts,
+      RunJSContextRegistry,
+      getRunJSDocFor,
+      FlowRunJSContext,
+    } = mod;
+
+    registerRunJSContextContribution(({ version, RunJSContextRegistry: Registry, FlowRunJSContext: BaseCtx }: any) => {
+      if (version !== 'v1') return;
+      class PluginTestRunJSContext extends BaseCtx {}
+      PluginTestRunJSContext.define({
+        properties: {
+          plugin: { description: 'plugin namespace', detail: 'object' },
+        },
+      });
+      Registry.register('v1', 'PluginTestModel', PluginTestRunJSContext, { scenes: ['block'] });
+    });
+
+    await setupRunJSContexts();
+
+    const ctor = RunJSContextRegistry.resolve('v1', 'PluginTestModel');
+    expect(ctor).toBeTruthy();
+    expect((ctor as any).name).toBe('PluginTestRunJSContext');
+
+    const ctx: any = { model: { constructor: { name: 'PluginTestModel' } } };
+    const doc = getRunJSDocFor(ctx, { version: 'v1' });
+    expect(doc?.properties?.plugin).toBeTruthy();
+
+    // Ensure FlowRunJSContext stays usable
+    expect(typeof FlowRunJSContext.getDoc).toBe('function');
+  });
+
+  it('should apply late contribution immediately after setup', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const { registerRunJSContextContribution, setupRunJSContexts, getRunJSDocFor, FlowContext } = mod;
+
+    await setupRunJSContexts();
+
+    registerRunJSContextContribution(({ version, FlowRunJSContext }: any) => {
+      if (version !== 'v1') return;
+      FlowRunJSContext.define({
+        properties: {
+          pluginLate: { description: 'late-added', detail: 'string' },
+        },
+      });
+    });
+
+    const ctx = new FlowContext();
+    const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+    expect(doc?.properties?.pluginLate).toBeTruthy();
+  });
+
+  it('should run each contribution at most once per version', async () => {
+    vi.resetModules();
+    const mod: any = await import('..');
+    const { registerRunJSContextContribution, setupRunJSContexts } = mod;
+
+    let count = 0;
+    const fn = ({ version }: any) => {
+      if (version !== 'v1') return;
+      count += 1;
+    };
+
+    registerRunJSContextContribution(fn);
+    registerRunJSContextContribution(fn); // duplicate registration should be ignored
+
+    await setupRunJSContexts();
+    await setupRunJSContexts();
+
+    expect(count).toBe(1);
+  });
+});