@nocobase/flow-engine 2.0.0-alpha.2

package/src/utils/variablesParams.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 type { JSONValue } from './params-resolvers';
+import type { Collection } from '../data-source';
+import { createCollectionContextMeta } from './createCollectionContextMeta';
+import { buildServerContextParams, type RecordRef, type ServerContextParams } from '../utils/serverContextParams';
+import {
+  extractUsedVariableNames as _extractUsedVariableNames,
+  extractUsedVariablePaths as _extractUsedVariablePaths,
+} from '@nocobase/utils/client';
+
+// Narrowest resource shape we rely on for inference
+type ResourceLike = {
+  getResourceName?: () => string;
+  getDataSourceKey?: () => string | undefined;
+  getFilterByTk?: () => unknown;
+  getSourceId?: () => unknown;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function getResource(ctx: FlowContext): ResourceLike | undefined {
+  const r = (ctx as FlowContext)['resource'];
+  return isObject(r) ? (r as ResourceLike) : undefined;
+}
+
+type CollectionShape = { name?: string; dataSourceKey?: string };
+
+function getCollection(ctx: FlowContext): CollectionShape | undefined {
+  const c = (ctx as FlowContext)['collection'] as unknown;
+  if (isObject(c)) {
+    const mc = c as Partial<CollectionShape>;
+    return { name: mc.name, dataSourceKey: mc.dataSourceKey };
+  }
+  return undefined;
+}
+
+export function inferRecordRef(ctx: FlowContext): RecordRef | undefined {
+  const resource = getResource(ctx);
+  const collectionObj = getCollection(ctx);
+
+  const resourceName = collectionObj?.name || resource?.getResourceName?.();
+  const dataSourceKey = collectionObj?.dataSourceKey || resource?.getDataSourceKey?.();
+  const filterByTk = resource?.getFilterByTk?.();
+
+  if (!resourceName || typeof filterByTk === 'undefined' || filterByTk === null) return undefined;
+  const parts = String(resourceName).split('.');
+  const collection = parts[parts.length - 1];
+  return { collection, dataSourceKey, filterByTk };
+}
+
+export function inferParentRecordRef(ctx: FlowContext): RecordRef | undefined {
+  const resource = getResource(ctx);
+  const dataSourceKey = getCollection(ctx)?.dataSourceKey || resource?.getDataSourceKey?.();
+  const rn = resource?.getResourceName?.();
+  const sourceId = resource?.getSourceId?.();
+  if (!rn || typeof sourceId === 'undefined' || sourceId === null) return undefined;
+  const parts = String(rn).split('.');
+  if (parts.length < 2) return undefined;
+  return { collection: parts[0], dataSourceKey, filterByTk: sourceId };
+}
+
+export type RecordParamsBuilder = (ctx: FlowContext) => RecordRef | Promise<RecordRef> | undefined;
+
+/**
+ * Build a PropertyMeta for a record-like property with variablesParams included.
+ */
+export async function buildRecordMeta(
+  collectionAccessor: () => Collection | null,
+  title?: string,
+  paramsBuilder?: RecordParamsBuilder,
+): Promise<PropertyMeta | null> {
+  const base = await createCollectionContextMeta(collectionAccessor, title)();
+  if (!base) return null;
+  return {
+    ...base,
+    buildVariablesParams: (ctx: FlowContext) => (paramsBuilder ? paramsBuilder(ctx) : inferRecordRef(ctx)),
+  } as PropertyMeta;
+}
+
+/**
+ * Convenience helper to create a PropertyMetaFactory for a record-like variable.
+ * It sets the factory.title so UI can display an immediate label before lazy resolution.
+ */
+export function createRecordMetaFactory(
+  collectionAccessor: () => Collection | null,
+  title: string,
+  paramsBuilder?: RecordParamsBuilder,
+): PropertyMetaFactory {
+  const factory: PropertyMetaFactory = async () => buildRecordMeta(collectionAccessor, title, paramsBuilder);
+  factory.title = title;
+  return factory;
+}
+
+/**
+ * Sugar for the most common case: a current record meta bound to FlowContext.
+ * - Title: t('Current record')
+ * - Params: inferRecordRef(ctx)
+ */
+export function createCurrentRecordMetaFactory(
+  ctx: FlowContext,
+  collectionAccessor: () => Collection | null,
+): PropertyMetaFactory {
+  const title = (ctx as any)?.t?.('Current record') || 'Current record';
+  return createRecordMetaFactory(collectionAccessor, title, (c) => inferRecordRef(c));
+}
+
+/**
+ * Extract top-level ctx variable names used inside a JSON template.
+ * Supports dot and bracket notations, e.g. {{ ctx.record.id }}, {{ ctx['parentRecord'].name }}.
+ */
+export const extractUsedVariableNames = _extractUsedVariableNames;
+
+/**
+ * Extract used top-level ctx variables with their subpaths.
+ * Returns a map: varName -> string[] subPaths
+ * Examples:
+ *  - {{ ctx.user.id }}        => { user: ['id'] }
+ *  - {{ ctx['user'].roles[0].name }} => { user: ['roles[0].name'] }
+ *  - {{ ctx.view.record.id }} => { view: ['record.id'] }
+ *  - {{ ctx.twice(21) }}      => { twice: [''] } // method call -> empty subPath
+ */
+export const extractUsedVariablePaths = _extractUsedVariablePaths;
+
+/**
+ * 根据模板中用到的 ctx 变量，收集并构建服务端解析所需的 contextParams。
+ * - 通过 FlowContext 的 PropertyMeta.buildVariablesParams 收集 RecordRef
+ * - 仅包含模板中实际使用到的顶层变量键，避免无谓膨胀
+ */
+export async function collectContextParamsForTemplate(
+  ctx: FlowContext,
+  template: JSONValue,
+): Promise<ServerContextParams | undefined> {
+  try {
+    const usage = _extractUsedVariablePaths(template) || {};
+    const varNames = Object.keys(usage);
+    if (!varNames.length) return undefined;
+
+    const input: Record<string, any> = {};
+    for (const key of varNames) {
+      const opt = (ctx as any).getPropertyOptions?.(key);
+      const meta: PropertyMeta | (() => Promise<PropertyMeta | null> | PropertyMeta | null) | undefined = opt?.meta;
+      if (!meta) continue;
+      let built: any;
+      try {
+        const resolvedMeta = typeof meta === 'function' ? await (meta as any)() : (meta as any);
+        const builder = resolvedMeta?.buildVariablesParams;
+        if (typeof builder === 'function') {
+          built = await builder(ctx);
+        }
+      } catch (err) {
+        // 忽略构建变量参数时的异常，继续处理其他变量
+        // 使用 void 引用以避免 no-unused-vars，同时避免空代码块触发 no-empty
+        void err;
+        continue;
+      }
+      if (built) {
+        input[key] = built;
+      }
+    }
+    return buildServerContextParams(ctx, input);
+  } catch (_) {
+    return undefined;
+  }
+}

package/src/views/DialogComponent.tsx

@@ -0,0 +1,79 @@
+/**
+ * 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 { Modal } from 'antd';
+import React, { forwardRef, useImperativeHandle, useState } from 'react';
+
+interface DialogComponentProps extends React.ComponentProps<typeof Modal> {
+  afterClose?: () => void;
+  content?: React.ReactNode;
+  footer?: React.ReactNode;
+  header?: { title?: React.ReactNode; extra?: React.ReactNode };
+  hidden?: boolean;
+}
+
+const DialogComponent = forwardRef<unknown, DialogComponentProps>(
+  ({ afterClose, footer: initialFooter, header: initialHeader, hidden, ...props }, ref) => {
+    const [visible, setVisible] = useState(true);
+    const [config, setConfig] = useState<any>(props);
+    const [footer, setFooter] = useState(() => initialFooter);
+    const [header, setHeader] = useState(initialHeader);
+
+    useImperativeHandle(ref, () => ({
+      destroy: () => {
+        setVisible(false);
+        afterClose?.();
+      },
+      update: (newConfig) => setConfig((prev) => ({ ...prev, ...newConfig })),
+      setFooter: (newFooter) => {
+        setFooter(newFooter);
+      },
+      setHeader: (newHeader) => {
+        if (Object.values(newHeader || {}).length === 0) {
+          setHeader(null);
+        } else {
+          setHeader(newHeader);
+        }
+      },
+    }));
+
+    // 处理 header 配置
+    const modalProps = {
+      ...config,
+      title: header?.title || config.title,
+      extra: header?.extra,
+      footer: footer !== undefined ? footer : config.footer ?? null,
+    };
+
+    const container = React.useMemo(() => {
+      return document.querySelector('#nocobase-app-container');
+    }, []);
+
+    return (
+      <Modal
+        closable={false}
+        rootClassName={hidden ? 'nb-hidden' : ''}
+        getContainer={container}
+        {...modalProps}
+        open={visible}
+        onCancel={(e) => {
+          setVisible(false);
+          config.onCancel?.(e);
+        }}
+        afterClose={() => {
+          afterClose?.();
+        }}
+      >
+        {config.children}
+      </Modal>
+    );
+  },
+);
+
+export default DialogComponent;

package/src/views/DrawerComponent.tsx

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+
+// components/drawer/useDrawer/DrawerComponent.tsx
+import { Drawer } from 'antd';
+import * as React from 'react';
+
+const DrawerComponent = React.forwardRef((props: any, ref) => {
+  const { children, footer: initialFooter, title, extra, hidden, ...drawerProps } = props;
+  const [open, setOpen] = React.useState(true);
+  const [footer, setFooter] = React.useState(() => initialFooter);
+  const [header, setHeader] = React.useState({ title, extra });
+
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      destroy: () => {
+        setOpen(false);
+        drawerProps.afterClose?.();
+      },
+      update: (newConfig) => {
+        // 更新 drawer 配置
+        Object.assign(drawerProps, newConfig);
+      },
+      setFooter: (newFooter) => {
+        setFooter(newFooter);
+      },
+      setHeader: (newHeader) => {
+        if (Object.values(newHeader || {}).length === 0) {
+          setHeader(null);
+        } else {
+          setHeader(newHeader);
+        }
+      },
+    }),
+    [],
+  );
+
+  const container = React.useMemo(() => {
+    return document.querySelector('#nocobase-app-container');
+  }, []);
+
+  return (
+    <Drawer
+      rootClassName={hidden ? 'nb-hidden' : ''}
+      closable={false}
+      getContainer={container}
+      {...drawerProps}
+      open={open}
+      footer={footer}
+      styles={{
+        ...drawerProps.styles,
+        footer: { display: 'flex', justifyContent: 'flex-end', ...drawerProps.styles?.footer },
+      }}
+      {...header} // 使用 extra 属性作为自定义 header
+      onClose={() => {
+        setOpen(false);
+        drawerProps.afterClose?.();
+      }}
+    >
+      {children}
+    </Drawer>
+  );
+});
+
+export default DrawerComponent;

package/src/views/FlowView.tsx

@@ -0,0 +1,103 @@
+/**
+ * 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 { PopoverProps as AntdPopoverProps } from 'antd';
+import { FlowContext } from '../flowContext';
+import { ViewNavigation } from './ViewNavigation';
+
+export type FlowView = {
+  type: 'drawer' | 'popover' | 'dialog' | 'embed';
+  inputArgs: any;
+  Header: React.FC<{ title?: React.ReactNode; extra?: React.ReactNode }> | null;
+  Footer: React.FC<{ children?: React.ReactNode }> | null;
+  close: (result?: any, force?: boolean) => void;
+  update: (newConfig: any) => void;
+  navigation?: ViewNavigation;
+  /** 页面的销毁方法 */
+  destroy?: () => void;
+  /** 提交流配置表单里的值。仅流配置视图中可访问到该方法 */
+  submit?: () => Promise<any>;
+};
+
+type TargetProps = {
+  target?: HTMLElement | string | null;
+};
+type ViewType = 'drawer' | 'popover' | 'dialog' | 'embed';
+type ViewProps = {
+  content: React.ReactNode | ((view: FlowView) => React.ReactNode);
+  width?: number | string;
+  /**
+   * 是否继承父类上下文
+   * @default true
+   */
+  inheritContext?: boolean;
+  /**
+   * 阻止关闭 View
+   */
+  preventClose?: boolean;
+  inputArgs?: any;
+  onOpen?: (view: FlowView, context: FlowContext) => void;
+  [key: string]: any;
+};
+
+type PopoverProps = AntdPopoverProps & {} & ViewProps & TargetProps;
+
+let zIndex = 0;
+
+export class FlowViewer {
+  public zIndex;
+
+  constructor(
+    protected ctx: FlowContext,
+    protected types: {
+      drawer: any;
+      popover: any;
+      dialog: any;
+      embed: any;
+    },
+  ) {
+    this.zIndex = zIndex + (ctx.themeToken?.zIndexPopupBase || 1000);
+  }
+
+  getNextZIndex() {
+    return this.zIndex + 1;
+  }
+
+  open(props: ViewProps & { type: ViewType } & TargetProps) {
+    const { type, ...others } = props;
+    if (this.types[type]) {
+      zIndex += 1;
+      const onClose = others.onClose;
+      const _zIndex = others.zIndex;
+      others.onClose = (...args) => {
+        onClose?.(...args);
+        zIndex -= 1;
+      };
+      // embed 不能设置过高的 zIndex，会遮挡菜单的折叠按钮图表
+      if (type !== 'embed') {
+        others.zIndex = _zIndex ?? this.getNextZIndex();
+      }
+      return this.types[type].open(others, this.ctx);
+    } else {
+      throw new Error(`Unknown view type: ${type}`);
+    }
+  }
+  dialog(props: ViewProps) {
+    return this.open({ type: 'dialog', ...props });
+  }
+  drawer(props: ViewProps) {
+    return this.open({ type: 'drawer', ...props });
+  }
+  popover(props: PopoverProps) {
+    return this.open({ type: 'popover', ...props });
+  }
+  embed(props: ViewProps & TargetProps) {
+    return this.open({ type: 'embed', ...props });
+  }
+}

package/src/views/PageComponent.tsx

@@ -0,0 +1,150 @@
+/**
+ * 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 { CloseOutlined } from '@ant-design/icons';
+import { Button } from 'antd';
+import React, { forwardRef, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { useFlowEngine } from '../provider';
+
+export const PageComponent = forwardRef((props: any, ref) => {
+  const [newConfig, setNewConfig] = React.useState<any>({});
+  const mergedProps: any = { ...props, ...newConfig };
+  const {
+    visible = true,
+    footer: _footer = null,
+    header: _header = null,
+    afterClose,
+    children,
+    hidden,
+    title: _title,
+    styles = {},
+    zIndex,
+  } = mergedProps;
+  const closedRef = useRef(false);
+  const flowEngine = useFlowEngine();
+  const [footer, setFooter] = useState(() => _footer);
+  const [header, setHeader] = useState(_header);
+
+  // 提供 destroy 和 update 能力
+  useImperativeHandle(ref, () => ({
+    destroy: () => {
+      if (!closedRef.current) {
+        closedRef.current = true;
+        afterClose?.();
+      }
+    },
+    update: (newConfig: any) => {
+      setNewConfig(newConfig);
+    },
+    setFooter: (newFooter) => {
+      setFooter(newFooter);
+    },
+    setHeader: (newHeader) => {
+      if (Object.values(newHeader || {}).length === 0) {
+        setHeader(null);
+      } else {
+        setHeader(newHeader);
+      }
+    },
+  }));
+
+  const style: React.CSSProperties = useMemo(
+    () => ({
+      display: hidden ? 'none' : 'flex',
+      flexDirection: 'column',
+      height: '100%',
+      zIndex,
+    }),
+    [hidden, zIndex],
+  );
+
+  // Header 组件
+  const HeaderComponent = useMemo(() => {
+    if (!header && !_title) return null;
+
+    const { title = _title, extra } = header || {};
+    const token = flowEngine.context.themeToken;
+
+    return (
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: `${token.paddingSM}px ${token.padding}px`,
+          borderBottom: `1px solid ${token.colorSplit}`,
+          backgroundColor: token.colorBgContainer,
+          ...styles.header,
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: token.marginXS }}>
+          <Button
+            type="text"
+            size="small"
+            icon={<CloseOutlined />}
+            onClick={() => {
+              if (!closedRef.current) {
+                closedRef.current = true;
+                afterClose?.();
+              }
+            }}
+            style={{
+              color: token.colorTextTertiary,
+            }}
+          />
+          {title && (
+            <div
+              style={{
+                fontSize: token.fontSizeLG,
+                fontWeight: token.fontWeightStrong,
+                color: token.colorText,
+              }}
+            >
+              {title}
+            </div>
+          )}
+        </div>
+        {extra && <div>{extra}</div>}
+      </div>
+    );
+  }, [header, _title, flowEngine.context.themeToken, styles.header, afterClose]);
+
+  // Footer 组件
+  const FooterComponent = useMemo(() => {
+    if (!footer) return null;
+
+    const token = flowEngine.context.themeToken;
+
+    return (
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'flex-end',
+          alignItems: 'center',
+          padding: `${token.paddingXS}px ${token.padding}px`,
+          borderTop: `1px solid ${token.colorSplit}`,
+          backgroundColor: token.colorBgContainer,
+          ...styles.footer,
+        }}
+      >
+        {footer}
+      </div>
+    );
+  }, [footer, flowEngine.context.themeToken, styles.footer]);
+
+  if (!visible) return null;
+
+  return (
+    <div style={{ ...style, ...styles.content }}>
+      {HeaderComponent}
+      <div style={{ flex: 1, overflowY: 'auto', ...styles.body }}>{children}</div>
+      {FooterComponent}
+    </div>
+  );
+});

package/src/views/ViewNavigation.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 { FlowEngineContext } from '../flowContext';
+
+interface ViewParam {
+  /** 视图唯一标识符，一般为某个 Model 实例的 uid */
+  viewUid?: string;
+  /** 标签页唯一标识符 */
+  tabUid?: string;
+  /** 弹窗记录的 id */
+  filterByTk?: string;
+  /** source Id */
+  sourceId?: string;
+}
+
+/**
+ * 将 ViewParam 数组转换为 pathname
+ *
+ * @param viewParams - ViewParam 数组
+ * @returns 生成的 pathname
+ *
+ * @example
+ * ```typescript
+ * generatePathnameFromViewParams([{ viewUid: 'xxx' }]) // '/admin/xxx'
+ * generatePathnameFromViewParams([{ viewUid: 'xxx', tabUid: 'yyy' }]) // '/admin/xxx/tab/yyy'
+ * generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy' }]) // '/admin/xxx/view/yyy'
+ * ```
+ */
+export function generatePathnameFromViewParams(viewParams: ViewParam[]): string {
+  if (!viewParams || viewParams.length === 0) {
+    return '/admin';
+  }
+
+  const segments = ['admin'];
+
+  viewParams.forEach((viewParam, index) => {
+    // 如果不是第一个视图，添加 'view' 关键字
+    if (index > 0) {
+      segments.push('view');
+    }
+
+    // 添加视图 UID
+    segments.push(viewParam.viewUid);
+
+    // 添加参数
+    if (viewParam.tabUid) {
+      segments.push('tab', viewParam.tabUid);
+    }
+    if (viewParam.filterByTk) {
+      segments.push('filterbytk', viewParam.filterByTk);
+    }
+    if (viewParam.sourceId) {
+      segments.push('sourceid', viewParam.sourceId);
+    }
+  });
+
+  return '/' + segments.join('/');
+}
+
+export class ViewNavigation {
+  viewStack: ViewParam[];
+  ctx: FlowEngineContext;
+
+  constructor(ctx: FlowEngineContext, viewParams: ViewParam[]) {
+    this.viewStack = [...viewParams];
+    this.ctx = ctx;
+  }
+
+  changeTo(viewParam: ViewParam) {
+    // 1. 根据传入的参数，改变当前视图的参数。当前视图的参数是 viewStack 中最后一个元素
+    if (this.viewStack.length === 0) {
+      this.viewStack.push(viewParam);
+    } else {
+      this.viewStack[this.viewStack.length - 1] = { ...this.viewStack[this.viewStack.length - 1], ...viewParam };
+    }
+
+    // 2. 根据 viewStack 生成新的 pathname
+    const newPathname = generatePathnameFromViewParams(this.viewStack);
+
+    // 3. 触发一次跳转。使用 replace 的方式
+    this.ctx.router.navigate(newPathname, { replace: true });
+  }
+
+  navigateTo(viewParam: ViewParam, opts?: { replace?: boolean; state?: any }) {
+    // 1. 基于当前 viewStack 生成一个 pathname
+    // 2. 将当前传入的参数转为 path string
+    const newViewPathname = generatePathnameFromViewParams([...this.viewStack, viewParam]);
+
+    // 3. 与 pathname 拼接成新的 pathname（这里直接使用新生成的 pathname）
+    const newPathname = newViewPathname;
+
+    // 4. 判断新的 pathname 是否与当前 location.pathname 的结尾一致。防止出现重复路径
+    //    不用 this.ctx.route.pathname 是因为它的值可能不是最新的，会导致判断失误
+    if (location.pathname.endsWith(newPathname)) {
+      return this.ctx.router.navigate(-1); // 避免点击按钮没反应的问题
+    }
+
+    // 5. 如果新的 pathname 与当前 ctx.route.pathname 不同，则触发一次跳转。使用 push 的方式
+    this.ctx.router.navigate(newPathname, opts);
+
+    // 6. 当 viewStack 为空时，把当前参数 push 到 viewStack 中
+    if (this.viewStack.length === 0) {
+      this.viewStack.push(viewParam);
+    }
+  }
+
+  back() {
+    const pathname = generatePathnameFromViewParams(this.viewStack);
+
+    // 防止重复触发返回操作
+    if (location.pathname.endsWith(pathname)) {
+      this.ctx.router.navigate(-1);
+    }
+  }
+}