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

package/src/__tests__/flowEngine.removeModel.test.ts

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { beforeEach, describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { FlowEngine } from '../flowEngine';
 import { FlowModel } from '../models';
 
@@ -20,6 +20,7 @@ describe('FlowEngine removeModel', () => {
   });
 
   it('removeModel should remove model but keep sub-models in cache (current behavior)', () => {
+    const loggerSpy = vi.spyOn(engine.logger, 'debug').mockImplementation(() => {});
     const parent = engine.createModel({ uid: 'parent', use: 'FlowModel' });
     const child = engine.createModel({
       uid: 'child',
@@ -32,14 +33,53 @@ describe('FlowEngine removeModel', () => {
     expect(engine.getModel('parent')).toBe(parent);
     expect(engine.getModel('child')).toBe(child);
 
-    engine.removeModel('parent');
+    try {
+      engine.removeModel('parent');
+    } finally {
+      loggerSpy.mockRestore();
+    }
 
     expect(engine.getModel('parent')).toBeUndefined();
     // Current behavior: child is still in cache
     expect(engine.getModel('child')).toBeDefined();
   });
 
+  it('removeModel should log missing models at debug level', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const loggerSpy = vi.spyOn(engine.logger, 'debug').mockImplementation(() => {});
+
+    try {
+      expect(engine.removeModel('missing')).toBe(false);
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+      expect(loggerSpy).toHaveBeenCalledWith("FlowEngine: Model with UID 'missing' does not exist.");
+    } finally {
+      consoleWarnSpy.mockRestore();
+      loggerSpy.mockRestore();
+    }
+  });
+
+  it('should reduce default logger verbosity in production', () => {
+    const originalNodeEnv = process.env.NODE_ENV;
+
+    try {
+      process.env.NODE_ENV = 'production';
+
+      const productionEngine = new FlowEngine();
+
+      expect(productionEngine.logger.level).toBe('warn');
+      expect(productionEngine.logger.isLevelEnabled('debug')).toBe(false);
+      expect(productionEngine.logger.isLevelEnabled('warn')).toBe(true);
+    } finally {
+      if (originalNodeEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = originalNodeEnv;
+      }
+    }
+  });
+
   it('removeModelWithSubModels should remove model and all sub-models from cache', () => {
+    const loggerSpy = vi.spyOn(engine.logger, 'debug').mockImplementation(() => {});
     const parent = engine.createModel({ uid: 'parent', use: 'FlowModel' });
     const child = engine.createModel({
       uid: 'child',
@@ -63,7 +103,11 @@ describe('FlowEngine removeModel', () => {
     expect(engine.getModel('child')).toBe(child);
     expect(engine.getModel('grandChild')).toBe(grandChild);
 
-    engine.removeModelWithSubModels('parent');
+    try {
+      engine.removeModelWithSubModels('parent');
+    } finally {
+      loggerSpy.mockRestore();
+    }
 
     expect(engine.getModel('parent')).toBeUndefined();
     expect(engine.getModel('child')).toBeUndefined();

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__/objectVariable.test.ts

@@ -26,6 +26,7 @@ function setupEngineWithCollections() {
     fields: [
       { name: 'id', type: 'integer', interface: 'number' },
       { name: 'name', type: 'string', interface: 'text' },
+      { name: 'rawUserPayload', type: 'json', filterable: true },
     ],
   });
   ds.addCollection({
@@ -41,6 +42,8 @@ function setupEngineWithCollections() {
     filterTargetKey: 'id',
     fields: [
       { name: 'title', type: 'string', interface: 'text' },
+      { name: 'internalName', type: 'string', interface: 'text' },
+      { name: 'rawPostPayload', type: 'json', filterable: true },
       { name: 'author', type: 'belongsTo', target: 'users', interface: 'm2o' },
       { name: 'tags', type: 'belongsToMany', target: 'tags', interface: 'm2m' },
     ],
@@ -91,6 +94,27 @@ describe('objectVariable utilities', () => {
     });
   });
 
+  it('createAssociationAwareObjectMetaFactory should hide fields without interface from object variable meta', async () => {
+    const { collection } = setupEngineWithCollections();
+    const obj = { title: 'hello', internalName: 'internal', rawPostPayload: { secret: true }, author: 1 };
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+
+    const meta = await metaFactory();
+    const props = await (meta?.properties as any)?.();
+    const authorFields = await props?.author?.properties?.();
+
+    expect(props).toHaveProperty('title');
+    expect(props).toHaveProperty('internalName');
+    expect(props).toHaveProperty('author');
+    expect(props).not.toHaveProperty('rawPostPayload');
+    expect(authorFields).toHaveProperty('name');
+    expect(authorFields).not.toHaveProperty('rawUserPayload');
+  });
+
   it('integrates with FlowContext.resolveJsonTemplate to call variables:resolve with flattened contextParams', async () => {
     const { engine, collection } = setupEngineWithCollections();
     const obj = { author: 1 };

package/src/__tests__/provider.test.tsx

@@ -9,9 +9,10 @@
 
 import React from 'react';
 import { describe, expect, it } from 'vitest';
-import { renderHook } from '@testing-library/react';
+import { render, renderHook } from '@testing-library/react';
+import { App, ConfigProvider, theme } from 'antd';
 import { FlowEngine } from '../flowEngine';
-import { FlowEngineProvider, useFlowEngine } from '../provider';
+import { FlowEngineGlobalsContextProvider, FlowEngineProvider, useFlowEngine } from '../provider';
 
 describe('FlowEngineProvider/useFlowEngine', () => {
   it('returns engine within provider', () => {
@@ -20,4 +21,25 @@ describe('FlowEngineProvider/useFlowEngine', () => {
     const { result } = renderHook(() => useFlowEngine(), { wrapper });
     expect(result.current).toBe(engine);
   });
+
+  it('registers isDarkTheme within globals provider before first child render', () => {
+    const engine = new FlowEngine();
+    const reads: boolean[] = [];
+    const Reader = () => {
+      reads.push(engine.context.isDarkTheme);
+      return null;
+    };
+    const wrapper = ({ children }: any) => (
+      <ConfigProvider theme={{ algorithm: theme.darkAlgorithm }}>
+        <App>
+          <FlowEngineProvider engine={engine}>
+            <FlowEngineGlobalsContextProvider>{children}</FlowEngineGlobalsContextProvider>
+          </FlowEngineProvider>
+        </App>
+      </ConfigProvider>
+    );
+    render(<Reader />, { wrapper });
+    expect(reads[0]).toBe(true);
+    expect(engine.context.isDarkTheme).toBe(true);
+  });
 });

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

@@ -38,6 +38,7 @@ describe('flowRunJSContext registry and doc', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',
@@ -58,8 +59,10 @@ describe('flowRunJSContext registry and doc', () => {
     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([]);
     });
@@ -85,6 +88,19 @@ describe('flowRunJSContext registry and doc', () => {
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc).toBeTruthy();
       expect(doc?.label).toMatch(/RunJS base/);
+      expect(doc?.properties?.element).toBeUndefined();
+    });
+
+    it('should mark element-dependent base completions with element requirement', () => {
+      const ctx: any = { model: { constructor: { name: 'UnknownModel' } } };
+      const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+
+      expect((doc?.methods?.render as any)?.completion?.requires).toContain('element');
+      expect((doc?.properties?.viewer as any)?.properties?.popover?.completion?.requires).toContain('element');
+      expect((doc?.properties?.viewer as any)?.properties?.embed?.completion?.requires).toContain('element');
+      expect(
+        (doc?.properties?.libs as any)?.properties?.ReactDOM?.properties?.createRoot?.completion?.requires,
+      ).toContain('element');
     });
 
     it('should support locale-specific doc', () => {
@@ -96,6 +112,11 @@ describe('flowRunJSContext registry and doc', () => {
       const messageText =
         typeof message === 'string' ? message : (message as any)?.description ?? (message as any)?.detail ?? '';
       expect(String(messageText)).toMatch(/Ant Design 全局消息/);
+      expect((doc?.methods?.render as any)?.completion?.requires).toContain('element');
+      expect((doc?.properties?.viewer as any)?.properties?.popover?.completion?.requires).toContain('element');
+      expect(
+        (doc?.properties?.libs as any)?.properties?.ReactDOM?.properties?.createRoot?.completion?.requires,
+      ).toContain('element');
     });
 
     it('should fallback to English when locale is not found', () => {

package/src/__tests__/runjsContextImplementations.test.ts

@@ -27,7 +27,10 @@ describe('Specific RunJSContext implementations', () => {
       const ctx: any = { model: { constructor: { name: 'JSColumnModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.properties?.element).toBeTruthy();
-      expect(doc?.properties?.element).toContain('ElementProxy');
+      const elementDoc: any = doc?.properties?.element;
+      expect(elementDoc?.detail).toContain('ElementProxy');
+      expect(elementDoc?.properties?.setAttribute).toBeTruthy();
+      expect(elementDoc?.properties?.querySelector).toBeTruthy();
     });
 
     it('should have record property in doc', () => {
@@ -68,7 +71,9 @@ describe('Specific RunJSContext implementations', () => {
       (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.label).toMatch(/JS 列/);
-      expect(doc?.properties?.element).toContain('表格单元格');
+      const elementDoc: any = doc?.properties?.element;
+      expect(elementDoc?.description).toContain('表格单元格');
+      expect(elementDoc?.properties?.addEventListener).toBeTruthy();
     });
 
     it('should create instance successfully', () => {
@@ -162,6 +167,7 @@ describe('Specific RunJSContext implementations', () => {
       const ctx: any = { model: { constructor: { name: 'JSRecordActionModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.properties?.record).toBeTruthy();
+      expect(doc?.properties?.element).toBeUndefined();
     });
 
     it('should have filterByTk property', () => {
@@ -184,6 +190,7 @@ describe('Specific RunJSContext implementations', () => {
       const ctx: any = { model: { constructor: { name: 'JSCollectionActionModel' } } };
       const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
       expect(doc?.properties?.resource).toBeTruthy();
+      expect(doc?.properties?.element).toBeUndefined();
     });
 
     it('should support zh-CN locale', () => {

package/src/__tests__/runjsContextRuntime.test.ts

@@ -186,6 +186,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',
@@ -237,6 +238,7 @@ describe('RunJS Context Runtime Behavior', () => {
         'JSBlockModel',
         'JSFieldModel',
         'JSItemModel',
+        'JSItemActionModel',
         'JSColumnModel',
         'FormJSFieldItemModel',
         'JSRecordActionModel',

package/src/__tests__/runjsLocales.test.ts

@@ -12,6 +12,10 @@ import { getRunJSDocFor } from '..';
 import { setupRunJSContexts } from '../runjs-context/setup';
 import { FlowContext } from '../flowContext';
 
+function getRunJSDocText(doc: unknown) {
+  return typeof doc === 'string' ? doc : (doc as any)?.description ?? (doc as any)?.detail ?? '';
+}
+
 describe('RunJS locales patch (engine doc)', () => {
   beforeAll(async () => {
     await setupRunJSContexts();
@@ -30,10 +34,7 @@ describe('RunJS locales patch (engine doc)', () => {
     (ctx as any).defineProperty('model', { value: { constructor: { name: 'JSBlockModel' } } });
     (ctx as any).defineProperty('api', { value: { auth: { locale: 'zh-CN' } } });
     const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
-    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 全局消息 API/);
-    expect(String(doc?.methods?.t || '')).toMatch(/国际化函数/);
+    expect(String(getRunJSDocText(doc?.properties?.message))).toMatch(/Ant Design 全局消息 API/);
+    expect(String(getRunJSDocText(doc?.methods?.t))).toMatch(/国际化函数/);
   });
 });

package/src/__tests__/runjsSnippets.test.ts

@@ -112,6 +112,27 @@ describe('RunJS Snippets', () => {
       expect(multiScene?.scenes).toEqual(expect.arrayContaining(['detail', 'table']));
       expect(multiScene?.groups).toEqual(expect.arrayContaining(['scene/detail', 'scene/table']));
     });
+
+    it('should expose new style snippets for matching contexts', async () => {
+      const tableSnippets = await listSnippetsForContext('JSColumnRunJSContext', 'v1', 'zh-CN');
+      const fieldSnippets = await listSnippetsForContext('FormJSFieldItemRunJSContext', 'v1', 'zh-CN');
+      const detailEventSnippets = await listSnippetsForContext('DetailsItemModel', 'v1', 'zh-CN');
+      const tableEventSnippets = await listSnippetsForContext('TableColumnModel', 'v1', 'zh-CN');
+
+      const tableStyle = tableSnippets.find((s) => s.ref === 'scene/table/set-cell-style');
+      expect(tableStyle?.name).toBe('表格字段样式设置');
+      expect(tableStyle?.body).toContain('ctx.model.props.onCell');
+      expect(tableStyle?.scenes).toEqual(['tableFieldEvent']);
+
+      const fieldStyle = fieldSnippets.find((s) => s.ref === 'scene/detail/set-field-style');
+      expect(fieldStyle?.name).toBe('设置表单项/详情项样式');
+      expect(fieldStyle?.body).toContain('ctx.model.props.style');
+      expect(fieldStyle?.scenes).toEqual(expect.arrayContaining(['detailFieldEvent', 'formFieldEvent']));
+      expect(fieldStyle?.groups).toEqual(expect.arrayContaining(['scene/detail', 'scene/form']));
+
+      expect(detailEventSnippets.some((s) => s.ref === 'scene/detail/set-field-style')).toBe(true);
+      expect(tableEventSnippets.some((s) => s.ref === 'scene/table/set-cell-style')).toBe(true);
+    });
   });
 
   describe('New snippets', () => {