@nocobase/flow-engine 2.1.0-beta.9 → 2.1.1

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

@@ -0,0 +1,130 @@
+/**
+ * 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 type { RunJSDocPropertyDoc } from '../../flowContext';
+
+const elementProperties: Record<string, RunJSDocPropertyDoc> = {
+  innerHTML: 'Sanitized inner HTML string.',
+  outerHTML: 'Sanitized outer HTML string.',
+  textContent: 'Text content.',
+  style: 'Inline style declaration.',
+  classList: 'DOMTokenList for CSS classes.',
+  appendChild: {
+    type: 'function',
+    description: 'Append a DOM node or text.',
+    detail: '(child: Node | string) => void',
+    completion: { insertText: `ctx.element.appendChild('text')` },
+  },
+  setAttribute: {
+    type: 'function',
+    description: 'Set an HTML attribute.',
+    detail: '(name: string, value: string) => void',
+    completion: { insertText: `ctx.element.setAttribute('data-key', 'value')` },
+  },
+  getAttribute: {
+    type: 'function',
+    description: 'Read an HTML attribute.',
+    detail: '(name: string) => string | null',
+    completion: { insertText: `ctx.element.getAttribute('data-key')` },
+  },
+  querySelector: {
+    type: 'function',
+    description: 'Find the first matching descendant.',
+    detail: '(selectors: string) => Element | null',
+    completion: { insertText: `ctx.element.querySelector('.selector')` },
+  },
+  querySelectorAll: {
+    type: 'function',
+    description: 'Find all matching descendants.',
+    detail: '(selectors: string) => NodeListOf<Element>',
+    completion: { insertText: `ctx.element.querySelectorAll('.selector')` },
+  },
+  addEventListener: {
+    type: 'function',
+    description: 'Attach an event listener to the element.',
+    detail: '(type: string, listener: EventListener) => void',
+    completion: { insertText: `ctx.element.addEventListener('click', (event) => {})` },
+  },
+  removeEventListener: {
+    type: 'function',
+    description: 'Remove an event listener from the element.',
+    detail: '(type: string, listener: EventListener) => void',
+    completion: { insertText: `ctx.element.removeEventListener('click', handler)` },
+  },
+};
+
+const zhCNElementProperties: Record<string, RunJSDocPropertyDoc> = {
+  innerHTML: '已消毒的 innerHTML 字符串。',
+  outerHTML: '已消毒的 outerHTML 字符串。',
+  textContent: '文本内容。',
+  style: '内联样式声明。',
+  classList: 'CSS class 列表。',
+  appendChild: {
+    type: 'function',
+    description: '追加 DOM 节点或文本。',
+    detail: '(child: Node | string) => void',
+    completion: { insertText: `ctx.element.appendChild('text')` },
+  },
+  setAttribute: {
+    type: 'function',
+    description: '设置 HTML 属性。',
+    detail: '(name: string, value: string) => void',
+    completion: { insertText: `ctx.element.setAttribute('data-key', 'value')` },
+  },
+  getAttribute: {
+    type: 'function',
+    description: '读取 HTML 属性。',
+    detail: '(name: string) => string | null',
+    completion: { insertText: `ctx.element.getAttribute('data-key')` },
+  },
+  querySelector: {
+    type: 'function',
+    description: '查询第一个匹配的后代元素。',
+    detail: '(selectors: string) => Element | null',
+    completion: { insertText: `ctx.element.querySelector('.selector')` },
+  },
+  querySelectorAll: {
+    type: 'function',
+    description: '查询所有匹配的后代元素。',
+    detail: '(selectors: string) => NodeListOf<Element>',
+    completion: { insertText: `ctx.element.querySelectorAll('.selector')` },
+  },
+  addEventListener: {
+    type: 'function',
+    description: '给元素添加事件监听。',
+    detail: '(type: string, listener: EventListener) => void',
+    completion: { insertText: `ctx.element.addEventListener('click', (event) => {})` },
+  },
+  removeEventListener: {
+    type: 'function',
+    description: '移除元素事件监听。',
+    detail: '(type: string, listener: EventListener) => void',
+    completion: { insertText: `ctx.element.removeEventListener('click', handler)` },
+  },
+};
+
+export function createElementPropertyDoc(
+  description = 'Current DOM container for this RunJS context. Usually an ElementProxy.',
+): RunJSDocPropertyDoc {
+  return {
+    description,
+    detail: 'HTMLElement | ElementProxy',
+    properties: elementProperties,
+  };
+}
+
+export function createZhCNElementPropertyDoc(
+  description = '当前 RunJS 上下文的 DOM 容器，通常为 ElementProxy。',
+): RunJSDocPropertyDoc {
+  return {
+    description,
+    detail: 'HTMLElement | ElementProxy',
+    properties: zhCNElementProperties,
+  };
+}

package/src/runjs-context/setup.ts

@@ -47,6 +47,7 @@ export async function setupRunJSContexts() {
     RunJSContextRegistry.register(version, 'JSFieldModel', JSFieldRunJSContext, { scenes: ['detail'] });
     RunJSContextRegistry.register(version, 'JSEditableFieldModel', JSEditableFieldRunJSContext, { scenes: ['form'] });
     RunJSContextRegistry.register(version, 'JSItemModel', JSItemRunJSContext, { scenes: ['form'] });
+    RunJSContextRegistry.register(version, 'JSItemActionModel', JSItemRunJSContext, { scenes: ['table'] });
     RunJSContextRegistry.register(version, 'JSColumnModel', JSColumnRunJSContext, { scenes: ['table'] });
     RunJSContextRegistry.register(version, 'FormJSFieldItemModel', FormJSFieldItemRunJSContext, { scenes: ['form'] });
     RunJSContextRegistry.register(version, 'JSRecordActionModel', JSRecordActionRunJSContext, { scenes: ['table'] });

package/src/runjs-context/snippets/index.ts

@@ -49,6 +49,7 @@ const snippets: Record<string, RunJSSnippetLoader | undefined> = {
   'scene/detail/status-tag': () => import('./scene/detail/status-tag.snippet'),
   'scene/detail/relative-time': () => import('./scene/detail/relative-time.snippet'),
   'scene/detail/percentage-bar': () => import('./scene/detail/percentage-bar.snippet'),
+  'scene/detail/set-field-style': () => import('./scene/detail/set-field-style.snippet'),
   // scene/form
   'scene/form/render-basic': () => import('./scene/form/render-basic.snippet'),
   'scene/form/set-field-value': () => import('./scene/form/set-field-value.snippet'),
@@ -67,6 +68,7 @@ const snippets: Record<string, RunJSSnippetLoader | undefined> = {
   'scene/table/iterate-selected-rows': () => import('./scene/table/iterate-selected-rows.snippet'),
   'scene/table/destroy-selected': () => import('./scene/table/destroy-selected.snippet'),
   'scene/table/export-selected-json': () => import('./scene/table/export-selected-json.snippet'),
+  'scene/table/set-cell-style': () => import('./scene/table/set-cell-style.snippet'),
 };
 
 export default snippets;
@@ -125,10 +127,19 @@ function normalizeScenes(def: any, key: string): string[] {
   return [];
 }
 
+function normalizeSceneGroup(scene: string): string {
+  const mapping: Record<string, string> = {
+    detailFieldEvent: 'detail',
+    tableFieldEvent: 'table',
+    formFieldEvent: 'form',
+  };
+  return mapping[scene] || scene;
+}
+
 function computeGroups(def: any, key: string): string[] {
   const scenes = normalizeScenes(def, key);
   if (scenes.length) {
-    return scenes.map((scene) => `scene/${scene}`);
+    return Array.from(new Set(scenes.map((scene) => `scene/${normalizeSceneGroup(scene)}`)));
   }
   const parts = key.split('/');
   if (!parts.length) return [];

package/src/runjs-context/snippets/scene/detail/set-field-style.snippet.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+const snippet: SnippetModule = {
+  contexts: ['*'],
+  scenes: ['detailFieldEvent', 'formFieldEvent'],
+  prefix: 'sn-item-style',
+  label: 'Set form item/details item style',
+  description: 'Customize form item and details item container styles',
+  locales: {
+    'zh-CN': {
+      label: '设置表单项/详情项样式',
+      description: '自定义表单项和详情项容器样式',
+    },
+  },
+  content: `
+ctx.model.props.style = {
+  background: 'red',
+};
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/scene/table/set-cell-style.snippet.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+const snippet: SnippetModule = {
+  contexts: ['*'],
+  scenes: ['tableFieldEvent'],
+  prefix: 'sn-table-cell-style',
+  label: 'Set table cell style',
+  description: 'Customize table field cell styles with onCell',
+  locales: {
+    'zh-CN': {
+      label: '表格字段样式设置',
+      description: '通过 onCell 自定义表格字段单元格样式',
+    },
+  },
+  content: `
+ctx.model.props.onCell = (record, rowIndex) => {
+  return {
+    style: {
+      background: 'red',
+    },
+  };
+};
+`,
+};
+
+export default snippet;

package/src/types.ts

@@ -145,6 +145,8 @@ export enum ActionScene {
   ACTION_LINKAGE_RULES,
   /** 动态事件流可用 */
   DYNAMIC_EVENT_FLOW,
+  /** 菜单项联动规则可用 */
+  MENU_LINKAGE_RULES,
 }
 
 /**
@@ -213,6 +215,7 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
  */
 export type FlowEventName =
   | 'click'
+  | 'close'
   | 'submit'
   | 'reset'
   | 'remove'
@@ -387,6 +390,65 @@ export interface CreateModelOptions {
   delegateToParent?: boolean;
   [key: string]: any; // 允许额外的自定义选项
 }
+
+/**
+ * FlowModel loader result.
+ * Supports returning the model constructor directly, a default export, or a module object containing the named export.
+ */
+export type FlowModelLoaderResult =
+  | ModelConstructor
+  | {
+      default?: ModelConstructor;
+      [key: string]: unknown;
+    }
+  | Record<string, unknown>;
+
+/**
+ * FlowModel loader function.
+ */
+export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
+
+/**
+ * FlowModel loader entry (normalized internal form).
+ */
+export interface FlowModelLoaderEntry {
+  loader: FlowModelLoader;
+  extends?: string[];
+  // meta?: Partial<FlowModelMeta>;
+  // scenes?: string[];
+}
+
+/**
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+  loader: FlowModelLoader;
+  extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+
+/**
+ * FlowModel loader entry map (normalized internal form).
+ */
+export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
+
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
+
+/**
+ * Batch ensure result.
+ */
+export interface EnsureBatchResult {
+  requested: string[];
+  loaded: string[];
+  failed: Array<{
+    name: string;
+    error?: unknown;
+  }>;
+}
+
 export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
   findOne(query: Record<string, any>): Promise<Record<string, any> | null>;
   save(model: T, options?: { onlyStepParams?: boolean }): Promise<Record<string, any>>;

package/src/utils/__tests__/createCollectionContextMeta.test.ts

@@ -26,6 +26,7 @@ describe('createCollectionContextMeta', () => {
         { name: 'id', type: 'integer', interface: 'number', filterable: true },
         { name: 'email', type: 'string', interface: 'text', filterable: true },
         { name: 'nickname', type: 'string', interface: 'text' }, // 未声明 filterable
+        { name: 'rawUserPayload', type: 'json', filterable: true },
       ],
     });
 
@@ -34,6 +35,7 @@ describe('createCollectionContextMeta', () => {
       fields: [
         { name: 'title', type: 'string', interface: 'text', filterable: true },
         { name: 'author', type: 'belongsTo', target: 'users', interface: 'm2o', filterable: true },
+        { name: 'rawPostPayload', type: 'json', filterable: true },
       ],
     });
 
@@ -44,8 +46,54 @@ describe('createCollectionContextMeta', () => {
     const authorMeta: any = props?.author;
     const authorFields = await authorMeta?.properties?.();
 
+    expect(props).toHaveProperty('title');
+    expect(props).toHaveProperty('author');
+    expect(props).not.toHaveProperty('rawPostPayload');
     expect(authorFields).toBeTruthy();
     expect(authorFields).toHaveProperty('email');
     expect(authorFields).not.toHaveProperty('nickname');
+    expect(authorFields).not.toHaveProperty('rawUserPayload');
+  });
+
+  it('keeps interfaced non-filterable fields but hides fields without interface when includeNonFilterable is true', async () => {
+    const engine = new FlowEngine();
+    const dm = engine.dataSourceManager as any;
+    dm.collectionFieldInterfaceManager = new CollectionFieldInterfaceManager([], {}, dm);
+    engine.context.defineProperty('app', { value: { dataSourceManager: dm } });
+    const ds = dm.getDataSource('main')!;
+
+    ds.addCollection({
+      name: 'users',
+      fields: [
+        { name: 'id', type: 'integer', interface: 'number', filterable: true },
+        { name: 'email', type: 'string', interface: 'text', filterable: true },
+        { name: 'nickname', type: 'string', interface: 'text' },
+        { name: 'rawUserPayload', type: 'json', filterable: true },
+      ],
+    });
+
+    ds.addCollection({
+      name: 'posts',
+      fields: [
+        { name: 'title', type: 'string', interface: 'text', filterable: true },
+        { name: 'internalName', type: 'string', interface: 'text' },
+        { name: 'rawPostPayload', type: 'json', filterable: true },
+        { name: 'author', type: 'belongsTo', target: 'users', interface: 'm2o', filterable: true },
+      ],
+    });
+
+    const posts = ds.getCollection('posts')!;
+    const metaFactory = createCollectionContextMeta(posts, 'Posts', true);
+    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('email');
+    expect(authorFields).toHaveProperty('nickname');
+    expect(authorFields).not.toHaveProperty('rawUserPayload');
   });
 });

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -102,6 +102,27 @@ describe('parsePathnameToViewParams', () => {
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
 
+  test('should parse custom root prefix', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { rootPrefix: 'embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by basePath', () => {
+    const result = parsePathnameToViewParams('/embed/xxx/tab/yyy/view/zzz', { basePath: '/embed' });
+    expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should parse pathname by nested basePath', () => {
+    const result = parsePathnameToViewParams('/admin/settings/public-forms/xxx/view/zzz', {
+      basePath: '/admin/settings/public-forms',
+    });
+    expect(result).toEqual([{ viewUid: 'xxx' }, { viewUid: 'zzz' }]);
+  });
+
+  test('should keep admin as default root prefix', () => {
+    expect(parsePathnameToViewParams('/embed/xxx')).toEqual([]);
+  });
+
   test('should parse filterByTk from key-value encoded segment into object', () => {
     const kv = encodeURIComponent('id=1&tenant=ac');
     const path = `/admin/xxx/filterbytk/${kv}`;

package/src/utils/__tests__/runjsValue.test.ts

@@ -41,4 +41,15 @@ describe('runjsValue utils', () => {
     expect(out.someVar).toContain('');
     expect(out.user).toContain('name');
   });
+
+  it('extractUsedVariablePathsFromRunJS: extracts ctx.getVar string paths', () => {
+    const code = `
+      const phone = await ctx.getVar('ctx.item.value.phone');
+      const assignee = await ctx.getVar("ctx.user.profile.name");
+      return [phone, assignee];
+    `;
+    const out = extractUsedVariablePathsFromRunJS(code);
+    expect(out.item).toContain('value.phone');
+    expect(out.user).toContain('profile.name');
+  });
 });

package/src/utils/__tests__/utils.test.ts

@@ -12,6 +12,7 @@ import {
   getT,
   isInheritedFrom,
   resolveDefaultParams,
+  shouldHideEventInSettings,
   resolveStepUiSchema,
   resolveStepDisabledInSettings,
   shouldHideStepInSettings,
@@ -27,6 +28,7 @@ import type {
   FlowDefinitionOptions,
   ActionDefinition,
   DeepPartial,
+  EventDefinition,
   ModelConstructor,
   StepParams,
   StepDefinition,
@@ -1002,6 +1004,66 @@ describe('Utils', () => {
     });
   });
 
+  // ==================== shouldHideEventInSettings() FUNCTION ====================
+  describe('shouldHideEventInSettings()', () => {
+    let mockFlow: any;
+    let mockEvent: EventDefinition;
+
+    beforeEach(() => {
+      mockFlow = {
+        key: 'testFlow',
+        title: 'Test Flow',
+        steps: {},
+      };
+
+      mockEvent = {
+        name: 'close',
+        title: 'Close',
+        handler: vi.fn(),
+      };
+    });
+
+    test('returns true for static hideInSettings=true', async () => {
+      mockEvent.hideInSettings = true;
+
+      const result = await shouldHideEventInSettings(mockModel, mockFlow, mockEvent);
+
+      expect(result).toBe(true);
+    });
+
+    test('returns false for static hideInSettings=false', async () => {
+      mockEvent.hideInSettings = false;
+
+      const result = await shouldHideEventInSettings(mockModel, mockFlow, mockEvent);
+
+      expect(result).toBe(false);
+    });
+
+    test('evaluates function hideInSettings with FlowRuntimeContext and can read ctx.view.preventClose', async () => {
+      mockModel.context.defineProperty('view', { value: { preventClose: true } });
+      const hideFn = vi.fn().mockImplementation((ctx) => !!ctx.view?.preventClose);
+      mockEvent.hideInSettings = hideFn as any;
+
+      const result = await shouldHideEventInSettings(mockModel, mockFlow, mockEvent);
+
+      expect(hideFn).toHaveBeenCalledTimes(1);
+      const ctx = hideFn.mock.calls[0][0] as FlowRuntimeContext;
+      expect(ctx).toBeInstanceOf(FlowRuntimeContext);
+      expect(result).toBe(true);
+    });
+
+    test('returns false and logs warning when event hideInSettings throws', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      mockEvent.hideInSettings = vi.fn().mockRejectedValue(new Error('boom')) as any;
+
+      const result = await shouldHideEventInSettings(mockModel, mockFlow, mockEvent);
+
+      expect(consoleSpy).toHaveBeenCalled();
+      expect(result).toBe(false);
+      consoleSpy.mockRestore();
+    });
+  });
+
   // ==================== shouldHideStepInSettings() FUNCTION ====================
   describe('shouldHideStepInSettings()', () => {
     let mockFlow: any;

package/src/utils/createCollectionContextMeta.ts

@@ -14,6 +14,10 @@ import type { PropertyMetaFactory } from '../flowContext';
 const RELATION_FIELD_TYPES = ['belongsTo', 'hasOne', 'hasMany', 'belongsToMany', 'belongsToArray'] as const;
 const NUMERIC_FIELD_TYPES = ['integer', 'float', 'double', 'decimal'] as const;
 
+function shouldShowFieldInMeta(field: CollectionField, includeNonFilterable?: boolean) {
+  return Boolean(field.interface && (includeNonFilterable || field.filterable));
+}
+
 /**
  * 创建字段的完整元数据（统一处理关联和非关联字段）
  */
@@ -36,7 +40,7 @@ function createFieldMetadata(field: CollectionField, includeNonFilterable?: bool
       properties: async () => {
         const subProperties: Record<string, any> = {};
         targetCollection.fields.forEach((subField) => {
-          if (includeNonFilterable || subField.filterable) {
+          if (shouldShowFieldInMeta(subField, includeNonFilterable)) {
             subProperties[subField.name] = createFieldMetadata(subField, includeNonFilterable);
           }
         });
@@ -114,7 +118,7 @@ export function createCollectionContextMeta(
 
         // 添加所有字段
         collection.fields.forEach((field) => {
-          if (includeNonFilterable || field.filterable) {
+          if (shouldShowFieldInMeta(field, includeNonFilterable)) {
             properties[field.name] = createFieldMetadata(field, includeNonFilterable);
           }
         });

package/src/utils/index.ts

@@ -22,7 +22,7 @@ export {
 export { escapeT, getT, tExpr } from './translation';
 
 // 异常类
-export { FlowCancelSaveException, FlowExitException } from './exceptions';
+export { FlowCancelSaveException, FlowExitAllException, FlowExitException } from './exceptions';
 
 // 流程定义相关
 export { defineAction } from './flow-definitions';
@@ -39,6 +39,7 @@ export {
   resolveStepUiSchema,
   resolveStepDisabledInSettings,
   resolveUiMode,
+  shouldHideEventInSettings,
   shouldHideStepInSettings,
 } from './schema-utils';
 
@@ -103,3 +104,6 @@ export { isBeforeRenderFlow } from './flows';
 
 // Module URL resolver
 export { resolveModuleUrl, isCssFile } from './resolveModuleUrl';
+
+// Random base36 identifier with optional semantic prefix
+export { randomId } from './randomId';