@nocobase/flow-engine 2.0.0-alpha.2

package/src/views/__tests__/FlowView.test.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { FlowViewer } from '../FlowView';
+
+describe('FlowViewer', () => {
+  const ctx: any = { t: (k: string) => k };
+  const open = vi.fn();
+  const types = { drawer: { open }, popover: { open }, dialog: { open }, embed: { open } } as any;
+
+  it('delegates to concrete viewer types with type field', () => {
+    const viewer = new FlowViewer(ctx, types);
+    viewer.dialog({ content: 'x' });
+    viewer.drawer({ content: 'x' });
+    viewer.popover({ content: 'x', title: 'p' } as any);
+    viewer.embed({ content: 'x' });
+    expect(open).toHaveBeenCalledTimes(4);
+  });
+
+  it('throws on unknown type in open', () => {
+    const viewer = new FlowViewer(ctx, { ...types, drawer: undefined } as any);
+    expect(() => viewer.open({ type: 'drawer', content: 'x' } as any)).toThrow(/Unknown view type/);
+  });
+});

package/src/views/__tests__/ViewNavigation.test.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 { ViewNavigation, generatePathnameFromViewParams } from '../ViewNavigation';
+
+describe('ViewNavigation', () => {
+  let mockCtx: any;
+  let viewNavigation: ViewNavigation;
+
+  beforeEach(() => {
+    mockCtx = {
+      router: {
+        navigate: vi.fn(),
+      },
+      route: {
+        pathname: '/admin/test',
+      },
+    };
+  });
+
+  describe('changeTo', () => {
+    it('should replace current view when viewStack is empty', () => {
+      viewNavigation = new ViewNavigation(mockCtx, []);
+
+      viewNavigation.changeTo({ viewUid: 'new-view' });
+
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'new-view' }]);
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin/new-view', { replace: true });
+    });
+
+    it('should replace last view in viewStack', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'old-view' }]);
+
+      viewNavigation.changeTo({ viewUid: 'new-view', tabUid: 'tab1' });
+
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'new-view', tabUid: 'tab1' }]);
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin/new-view/tab/tab1', { replace: true });
+    });
+
+    it('should replace last view with complex parameters', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }, { viewUid: 'view2', tabUid: 'tab1' }]);
+
+      viewNavigation.changeTo({
+        viewUid: 'new-view',
+        tabUid: 'new-tab',
+        filterByTk: '123',
+        sourceId: 'source1',
+      });
+
+      expect(viewNavigation.viewStack).toEqual([
+        { viewUid: 'view1' },
+        { viewUid: 'new-view', tabUid: 'new-tab', filterByTk: '123', sourceId: 'source1' },
+      ]);
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith(
+        '/admin/view1/view/new-view/tab/new-tab/filterbytk/123/sourceid/source1',
+        { replace: true },
+      );
+    });
+
+    it('should allow omitting viewUid', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.changeTo({ tabUid: 'new-tab' });
+
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'view1', tabUid: 'new-tab' }]);
+    });
+  });
+
+  describe('navigateTo', () => {
+    it('should navigate to new view', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'current-view' }]);
+
+      viewNavigation.navigateTo({ viewUid: 'new-view' });
+
+      // viewStack 保持不变
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'current-view' }]);
+      const call = (mockCtx.router.navigate as any).mock.calls[0];
+      expect(call[0]).toBe('/admin/current-view/view/new-view');
+      expect(call[1]).toBeUndefined();
+    });
+
+    it('should navigate back when pathname is the same', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+      // set browser location to match the generated pathname
+      window.history.pushState({}, '', '/admin/view1/view/view2');
+
+      viewNavigation.navigateTo({ viewUid: 'view2' });
+
+      // when same pathname, navigate(-1) to avoid "no reaction" UX
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith(-1);
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'view1' }]);
+    });
+
+    it('should navigate with complex parameters', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1', tabUid: 'tab1' }]);
+
+      viewNavigation.navigateTo({
+        viewUid: 'view2',
+        tabUid: 'tab2',
+        filterByTk: '456',
+        sourceId: 'source2',
+      });
+
+      // viewStack 保持不变
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'view1', tabUid: 'tab1' }]);
+      const call = (mockCtx.router.navigate as any).mock.calls[0];
+      expect(call[0]).toBe('/admin/view1/tab/tab1/view/view2/tab/tab2/filterbytk/456/sourceid/source2');
+      expect(call[1]).toBeUndefined();
+    });
+
+    it('should navigate from empty viewStack', () => {
+      viewNavigation = new ViewNavigation(mockCtx, []);
+
+      viewNavigation.navigateTo({ viewUid: 'first-view' });
+
+      expect(viewNavigation.viewStack).toEqual([{ viewUid: 'first-view' }]);
+      const call = (mockCtx.router.navigate as any).mock.calls[0];
+      expect(call[0]).toBe('/admin/first-view');
+      expect(call[1]).toBeUndefined();
+    });
+  });
+
+  describe('back', () => {
+    it('should call router navigate with -1', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+      // set browser location to current stack pathname so back() triggers
+      window.history.pushState({}, '', '/admin/view1');
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith(-1);
+    });
+  });
+});
+
+describe('generatePathnameFromViewParams', () => {
+  it('should handle empty array', () => {
+    expect(generatePathnameFromViewParams([])).toBe('/admin');
+    expect(generatePathnameFromViewParams(null as any)).toBe('/admin');
+    expect(generatePathnameFromViewParams(undefined as any)).toBe('/admin');
+  });
+
+  it('should generate single view path', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');
+  });
+
+  it('should generate view with tab', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx', tabUid: 'yyy' }])).toBe('/admin/xxx/tab/yyy');
+  });
+
+  it('should generate multiple views', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy' }])).toBe('/admin/xxx/view/yyy');
+  });
+
+  it('should generate complex path with all parameters', () => {
+    expect(
+      generatePathnameFromViewParams([
+        { viewUid: 'xxx', tabUid: 'tab1' },
+        { viewUid: 'yyy', tabUid: 'tab2', filterByTk: '123', sourceId: 'source1' },
+      ]),
+    ).toBe('/admin/xxx/tab/tab1/view/yyy/tab/tab2/filterbytk/123/sourceid/source1');
+  });
+
+  it('should handle filterByTk and sourceId without tab', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx', filterByTk: '1', sourceId: '2' }])).toBe(
+      '/admin/xxx/filterbytk/1/sourceid/2',
+    );
+  });
+
+  it('should match parsePathnameToViewParams test cases', () => {
+    // Test cases from parsePathnameToViewParams.test.ts
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx', tabUid: 'yyy' }])).toBe('/admin/xxx/tab/yyy');
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy' }])).toBe('/admin/xxx/view/yyy');
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy', tabUid: 'zzz' }])).toBe(
+      '/admin/xxx/view/yyy/tab/zzz',
+    );
+    expect(
+      generatePathnameFromViewParams([
+        { viewUid: 'xxx', tabUid: 'yyy' },
+        { viewUid: 'zzz', tabUid: 'aaa' },
+      ]),
+    ).toBe('/admin/xxx/tab/yyy/view/zzz/tab/aaa');
+  });
+});

package/src/views/__tests__/usePatchElement.test.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 from 'react';
+import { describe, expect, it } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import usePatchElement from '../usePatchElement';
+
+describe('usePatchElement', () => {
+  it('adds and removes elements', () => {
+    const { result } = renderHook(() => usePatchElement<JSX.Element>());
+    const el = <div>Hi</div>;
+    let dispose: () => void;
+    act(() => {
+      const [_, patch] = result.current;
+      dispose = patch(el);
+    });
+    expect(result.current[0].length).toBe(1);
+    act(() => dispose());
+    expect(result.current[0].length).toBe(0);
+  });
+});

package/src/views/createViewMeta.ts

@@ -0,0 +1,157 @@
+/**
+ * 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 { FlowContext, PropertyMeta, PropertyMetaFactory } from '../flowContext';
+import { inferRecordRef, buildRecordMeta } from '../utils/variablesParams';
+
+// 判断是否为普通对象（Plain Object），避免对类实例/代理等进行深度遍历
+function isPlainObject(val: any) {
+  if (val === null || typeof val !== 'object') return false;
+  const proto = Object.getPrototypeOf(val);
+  return proto === Object.prototype || proto === null;
+}
+
+// 懒加载元信息：仅在展开节点时计算子属性；并加入循环引用防护
+function makeMetaFromValue(value: any, title?: string, seen?: WeakSet<any>): any {
+  const t = typeof value;
+  if (value === null || value === undefined) return { type: 'any', title };
+
+  if (Array.isArray(value)) {
+    return {
+      type: 'array',
+      title,
+      properties: async () => {
+        const max = Math.min(value.length || 0, 10);
+        const children: Record<string, any> = {};
+        const nextSeen = seen ?? new WeakSet<any>();
+        for (let i = 0; i < max; i++) {
+          children[String(i)] = makeMetaFromValue(value[i], `#${i}`, nextSeen);
+        }
+        return children;
+      },
+    };
+  }
+
+  if (t === 'string') return { type: 'string', title };
+  if (t === 'number') return { type: 'number', title };
+  if (t === 'boolean') return { type: 'boolean', title };
+
+  // 仅对普通对象做懒递归；其它对象（如运行时实例）视为 any，防止进入复杂的循环引用
+  if (t === 'object' && isPlainObject(value)) {
+    return {
+      type: 'object',
+      title,
+      properties: async () => {
+        const nextSeen = seen ?? new WeakSet<any>();
+        if (nextSeen.has(value)) {
+          // 循环引用：不再展开子节点
+          return {};
+        }
+        nextSeen.add(value);
+        const props: Record<string, any> = {};
+        Object.keys(value || {}).forEach((k) => {
+          props[k] = makeMetaFromValue(value[k], k, nextSeen);
+        });
+        return props;
+      },
+    };
+  }
+  return { type: 'any', title };
+}
+
+function buildNavigationMeta(ctx: FlowContext, getView: () => any): any {
+  // 与运行时对象保持一致：无 current，仅暴露 viewStack；并动态展开 viewStack 项
+  const t = (key: string) => (ctx as any)?.t?.(key) || key;
+  return {
+    type: 'object',
+    title: t('导航'),
+    properties: async () => {
+      const view = getView();
+      const nav = view?.navigation;
+      const props: Record<string, any> = {};
+
+      // 动态 viewStack：按索引展开，并为每个项提供字段
+      const stack = Array.isArray(nav?.viewStack) ? nav.viewStack : [];
+      const stackMeta: any = {
+        type: 'array',
+        title: t('视图堆栈'),
+        properties: undefined as Record<string, any> | undefined,
+      };
+      if (stack.length) {
+        const children: Record<string, any> = {};
+        const max = Math.min(stack.length, 20);
+        for (let i = 0; i < max; i++) {
+          const item = stack[i] || {};
+          children[String(i)] = {
+            type: 'object',
+            title: `#${i}`,
+            properties: {
+              viewUid: { type: 'string', title: 'viewUid' },
+              tabUid: { type: 'string', title: 'tabUid' },
+              filterByTk: { type: 'string', title: 'filterByTk' },
+              sourceId: { type: 'string', title: 'sourceId' },
+            },
+          };
+        }
+        stackMeta.properties = children;
+      }
+
+      props.viewStack = stackMeta;
+      return props;
+    },
+  };
+}
+
+/**
+ * Create a meta factory for ctx.view that includes:
+ * - buildVariablesParams: { record } via inferRecordRef
+ * - properties.record: full collection meta via buildRecordMeta
+ * - type/preventClose/inputArgs/navigation fields for better variable selection UX
+ */
+export function createViewMeta(ctx: FlowContext, getView: () => any): PropertyMetaFactory {
+  const viewTitle = (ctx as any)?.t?.('当前视图') || '当前视图';
+  const factory: PropertyMetaFactory = async () => {
+    const recordMeta = await buildRecordMeta(
+      () => {
+        try {
+          const ref = inferRecordRef(ctx);
+          if (!ref?.collection) return null;
+          const ds = ctx.dataSourceManager?.getDataSource?.(ref.dataSourceKey || 'main');
+          return ds?.collectionManager?.getCollection?.(ref.collection) || null;
+        } catch (e) {
+          return null;
+        }
+      },
+      (ctx as any)?.t?.('当前视图记录') || '当前视图记录',
+      (c) => inferRecordRef(c),
+    );
+
+    const view = getView();
+    return {
+      type: 'object',
+      title: viewTitle,
+      buildVariablesParams: (c) => {
+        const ref = inferRecordRef(c);
+        return ref ? { record: ref } : undefined;
+      },
+      properties: async () => {
+        const props: Record<string, any> = {};
+        if (recordMeta) props.record = recordMeta;
+        props.type = { type: 'string', title: (ctx as any)?.t?.('类型') || '类型' };
+        props.preventClose = { type: 'boolean', title: (ctx as any)?.t?.('是否允许关闭') || '是否允许关闭' };
+        props.inputArgs = makeMetaFromValue(view?.inputArgs, (ctx as any)?.t?.('输入参数') || '输入参数');
+        props.navigation = buildNavigationMeta(ctx, getView);
+        return props;
+      },
+    } as PropertyMeta;
+  };
+  // 设置工厂函数的 title，让未加载前的占位标题就是“当前视图”
+  factory.title = viewTitle;
+  return factory;
+}

package/src/views/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+export { useDialog } from './useDialog';
+export { useDrawer } from './useDrawer';
+export { usePage } from './usePage';
+export { usePopover } from './usePopover';
+export { ViewNavigation } from './ViewNavigation';

package/src/views/useDialog.tsx

@@ -0,0 +1,192 @@
+/**
+ * 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 * as React from 'react';
+import DOMPurify from 'dompurify';
+import { observer } from '..';
+import { FlowContext } from '../flowContext';
+import { FlowViewContextProvider } from '../FlowContextProvider';
+import { createViewMeta } from './createViewMeta';
+import DialogComponent from './DialogComponent';
+import usePatchElement from './usePatchElement';
+import { FlowEngineProvider } from '../provider';
+import { createViewScopedEngine } from '../ViewScopedFlowEngine';
+
+let uuid = 0;
+
+export function useDialog() {
+  const holderRef = React.useRef(null);
+
+  const open = (config, flowContext) => {
+    uuid += 1;
+    const dialogRef = React.createRef<{
+      destroy: () => void;
+      update: (config: any) => void;
+      setFooter: (footer: React.ReactNode) => void;
+      setHeader: (header: { title?: React.ReactNode; extra?: React.ReactNode }) => void;
+    }>();
+
+    // eslint-disable-next-line prefer-const
+    let closeFunc: (() => void) | undefined;
+    let resolvePromise: (value?: any) => void;
+    const promise = new Promise((resolve) => {
+      resolvePromise = resolve;
+    });
+
+    // 使用普通变量来存储状态
+    let currentFooter: React.ReactNode = null;
+    let currentHeader: any = null;
+
+    // Footer 组件实现
+    const FooterComponent = ({ children, ...props }) => {
+      React.useEffect(() => {
+        currentFooter = children;
+        dialogRef.current?.setFooter(children);
+
+        return () => {
+          currentFooter = null;
+          dialogRef.current?.setFooter(null);
+        };
+      }, [children]);
+
+      return null; // Footer 组件本身不渲染内容
+    };
+
+    // Header 组件实现
+    const HeaderComponent = ({ ...props }) => {
+      React.useEffect(() => {
+        currentHeader = props;
+        dialogRef.current?.setHeader(props as any);
+
+        return () => {
+          currentHeader = null;
+          dialogRef.current?.setHeader(null);
+        };
+      }, [props]);
+
+      return null; // Header 组件本身不渲染内容
+    };
+
+    // 构造 currentDialog 实例
+    const currentDialog = {
+      type: 'dialog',
+      inputArgs: config.inputArgs || {},
+      preventClose: !!config.preventClose,
+      destroy: () => dialogRef.current?.destroy(),
+      update: (newConfig) => dialogRef.current?.update(newConfig),
+      close: (result?: any, force?: boolean) => {
+        if (config.preventClose && !force) {
+          return;
+        }
+        dialogRef.current?.destroy();
+        closeFunc?.();
+        resolvePromise?.(result);
+      },
+      Footer: FooterComponent,
+      Header: HeaderComponent,
+      setFooter: (footer: React.ReactNode) => {
+        currentFooter = footer;
+        dialogRef.current?.setFooter(footer);
+      },
+      setHeader: (header: { title?: React.ReactNode; extra?: React.ReactNode }) => {
+        currentHeader = header;
+        dialogRef.current?.setHeader(header);
+      },
+      navigation: config.inputArgs?.navigation,
+    };
+
+    const ctx = new FlowContext();
+    ctx.defineProperty('view', {
+      get: () => currentDialog,
+      meta: createViewMeta(ctx, () => currentDialog),
+      resolveOnServer: (p: string) => p === 'record' || p.startsWith('record.'),
+    });
+    // 为当前视图创建作用域引擎（隔离实例与缓存）
+    const scopedEngine = createViewScopedEngine(flowContext.engine);
+    ctx.defineProperty('engine', { value: scopedEngine });
+    ctx.addDelegate(scopedEngine.context);
+    if (config.inheritContext !== false) {
+      ctx.addDelegate(flowContext);
+    } else {
+      ctx.addDelegate(flowContext.engine.context);
+    }
+
+    // 内部组件，在 Provider 内部计算 content
+    const DialogWithContext = observer(
+      () => {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const mountedRef = React.useRef(false);
+        const rawContent = typeof config.content === 'function' ? config.content(currentDialog, ctx) : config.content;
+        const content =
+          typeof rawContent === 'string' ? (
+            <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(rawContent) }} />
+          ) : (
+            rawContent
+          );
+
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        React.useEffect(() => {
+          config.onOpen?.(currentDialog, ctx);
+        }, []);
+
+        if (config.inputArgs?.hidden?.value && !mountedRef.current) {
+          return null;
+        }
+
+        mountedRef.current = true;
+
+        return (
+          <DialogComponent
+            className="nb-dialog-overflow-hidden"
+            key={`dialog-${uuid}`}
+            ref={dialogRef}
+            hidden={config.inputArgs?.hidden?.value}
+            {...config}
+            footer={currentFooter}
+            header={currentHeader}
+            afterClose={() => {
+              closeFunc?.();
+              config.onClose?.();
+              resolvePromise?.(config.result);
+              // 关闭时修正 previous/next 指针
+              scopedEngine.unlinkFromStack();
+            }}
+          >
+            {content}
+          </DialogComponent>
+        );
+      },
+      {
+        displayName: 'DialogWithContext',
+      },
+    );
+
+    const dialog = (
+      <FlowEngineProvider engine={scopedEngine}>
+        <FlowViewContextProvider context={ctx}>
+          <DialogWithContext />
+        </FlowViewContextProvider>
+      </FlowEngineProvider>
+    );
+
+    closeFunc = holderRef.current?.patchElement(dialog);
+    return Object.assign(promise, currentDialog);
+  };
+
+  const api = React.useMemo(() => ({ open }), []);
+  const ElementsHolder = React.memo(
+    React.forwardRef((props, ref) => {
+      const [elements, patchElement] = usePatchElement();
+      React.useImperativeHandle(ref, () => ({ patchElement }), [patchElement]);
+      return <>{elements}</>;
+    }),
+  );
+
+  return [api, <ElementsHolder key="dialog-holder" ref={holderRef} />];
+}