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

package/src/utils/loadedPageCache.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 { FlowModel } from '../models';
+
+type LoadedPageOptions = {
+  parentId?: string;
+  subKey?: string;
+};
+
+type DirtyKeyOptions = {
+  force?: boolean;
+};
+
+type FlowSettingsContextLike = {
+  flowSettingsEnabled?: boolean;
+};
+
+type FlowEngineLike = {
+  context?: FlowSettingsContextLike;
+  previousEngine?: FlowEngineLike;
+};
+
+const getLoadedPageKey = (options?: LoadedPageOptions): string | undefined => {
+  const parentId = options?.parentId;
+  const subKey = options?.subKey;
+  if (!parentId || subKey !== 'page') {
+    return undefined;
+  }
+  return `${parentId}::${subKey}`;
+};
+
+const getLoadedPageKeyFromModel = (model?: FlowModel | null): string | undefined => {
+  let current = model;
+  while (current) {
+    if (current.subKey === 'page' && current.parent?.uid) {
+      return getLoadedPageKey({ parentId: current.parent.uid, subKey: current.subKey });
+    }
+    current = current.parent as FlowModel | undefined;
+  }
+  return undefined;
+};
+
+const isFlowSettingsEnabledForContext = (context?: FlowSettingsContextLike): boolean => {
+  try {
+    return !!context?.flowSettingsEnabled;
+  } catch (error) {
+    return false;
+  }
+};
+
+const isFlowSettingsEnabledForModel = (model?: FlowModel | null): boolean => {
+  if (isFlowSettingsEnabledForContext(model?.context as FlowSettingsContextLike | undefined)) {
+    return true;
+  }
+
+  const visited = new Set<FlowEngineLike>();
+  let engine = model?.flowEngine as FlowEngineLike | undefined;
+  while (engine && !visited.has(engine)) {
+    visited.add(engine);
+    if (isFlowSettingsEnabledForContext(engine.context)) {
+      return true;
+    }
+    engine = engine.previousEngine;
+  }
+  return false;
+};
+
+const removeLoadedModelTree = (model?: FlowModel | null): void => {
+  if (!model?.uid || !model.flowEngine) {
+    return;
+  }
+  if (model.flowEngine.getModel(model.uid) === model) {
+    model.flowEngine.removeModelWithSubModels(model.uid);
+  }
+};
+
+const mountLoadedModelToParent = <T extends FlowModel = FlowModel>(model: T | null, forceReplace = false): T | null => {
+  if (!model?.parent || !model.subKey) {
+    return model;
+  }
+
+  const mounted = (model.parent.subModels as any)?.[model.subKey];
+  const existing =
+    forceReplace && model.subType !== 'array' && mounted && !Array.isArray(mounted)
+      ? (mounted as FlowModel)
+      : model.parent.findSubModel(model.subKey, (m) => m.uid === model.uid);
+  if (existing) {
+    if (!forceReplace || existing === model) {
+      return model;
+    }
+    removeLoadedModelTree(existing);
+  }
+
+  if (model.subType === 'array') {
+    model.parent.addSubModel(model.subKey, model);
+  } else {
+    model.parent.setSubModel(model.subKey, model);
+  }
+  return model;
+};
+
+export const createLoadedPageCache = () => {
+  const dirtyKeys = new Set<string>();
+
+  return {
+    getDirtyKeyForModel(model?: FlowModel | null, options?: DirtyKeyOptions): string | undefined {
+      if (!options?.force && !isFlowSettingsEnabledForModel(model)) {
+        return undefined;
+      }
+      return getLoadedPageKeyFromModel(model);
+    },
+
+    markDirty(key?: string): void {
+      if (key) {
+        dirtyKeys.add(key);
+      }
+    },
+
+    shouldBypass(options?: LoadedPageOptions, isFlowSettingsEnabled?: () => boolean): boolean {
+      const key = getLoadedPageKey(options);
+      if (!key || !dirtyKeys.has(key)) {
+        return false;
+      }
+      try {
+        return !isFlowSettingsEnabled?.();
+      } catch (error) {
+        return true;
+      }
+    },
+
+    clear(options?: LoadedPageOptions): void {
+      const key = getLoadedPageKey(options);
+      if (key) {
+        dirtyKeys.delete(key);
+      }
+    },
+
+    mountModelToParent: mountLoadedModelToParent,
+  };
+};

package/src/utils/parsePathnameToViewParams.ts

@@ -18,6 +18,35 @@ export interface ViewParam {
   sourceId?: string;
 }
 
+export interface ParsePathnameToViewParamsOptions {
+  rootPrefix?: string;
+  basePath?: string;
+}
+
+const normalizePathname = (pathname: string) => {
+  if (!pathname || pathname === '/') {
+    return '/';
+  }
+  return `/${pathname.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+};
+
+const normalizeBasePath = (basePath: string) => `/${basePath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+
+const stripBasePath = (pathname: string, basePath: string) => {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedBasePath = normalizeBasePath(basePath);
+
+  if (normalizedPathname === normalizedBasePath) {
+    return '';
+  }
+
+  if (normalizedPathname.startsWith(`${normalizedBasePath}/`)) {
+    return normalizedPathname.slice(normalizedBasePath.length + 1);
+  }
+
+  return '';
+};
+
 /**
  * 解析路径名为视图参数数组
  *
@@ -33,15 +62,21 @@ export interface ViewParam {
  * parsePathnameToViewParams('/admin/xxx/view/yyy') // [{ viewUid: 'xxx' }, { viewUid: 'yyy' }]
  * ```
  */
-export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
+export const parsePathnameToViewParams = (
+  pathname: string,
+  options: ParsePathnameToViewParamsOptions = {},
+): ViewParam[] => {
   if (!pathname || pathname === '/') {
     return [];
   }
 
+  const rootPrefix = options.rootPrefix || 'admin';
+  const relativePath = options.basePath ? stripBasePath(pathname, options.basePath) : '';
+
   // 移除开头的斜杠并分割路径
-  const segments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
+  const segments = (options.basePath ? relativePath : pathname).replace(/^\/+/, '').split('/').filter(Boolean);
 
-  if (segments.length < 2) {
+  if (segments.length < (options.basePath ? 1 : 2)) {
     return [];
   }
 
@@ -49,11 +84,16 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
   let currentView: ViewParam | null = null;
   let i = 0;
 
+  if (options.basePath) {
+    currentView = { viewUid: segments[0] };
+    i = 1;
+  }
+
   while (i < segments.length) {
     const segment = segments[i];
 
-    // 处理 admin 或 view 关键字
-    if (segment === 'admin' || segment === 'view') {
+    // 处理布局根前缀或 view 关键字
+    if (segment === rootPrefix || segment === 'view') {
       // 如果有当前视图，先保存到结果中
       if (currentView) {
         result.push(currentView);

package/src/utils/randomId.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+
+const CHARSET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+/**
+ * Generate a random base36 identifier with an optional semantic prefix.
+ *
+ * Equivalent in shape to v1's `uid()` from `@formily/shared` (11 chars
+ * of `[0-9a-z]`), with an opt-in prefix appended at the front. v2 forbids
+ * direct `@formily/*` imports in `src/client-v2/`, so this helper is the
+ * single substitute the rest of the codebase should reach for.
+ *
+ * Common semantic prefixes observed across the codebase — pass the one
+ * that matches your domain rather than relying on a default, so the
+ * intent is explicit at the call site:
+ *
+ *   - `s_` — service / settings record (authenticators, channels, …)
+ *   - `v_` — verifier / variable / LLM service
+ *   - `f_` — field
+ *   - `t_` — through table
+ *
+ * Example:
+ *
+ * ```ts
+ * import { randomId } from '@nocobase/flow-engine';
+ *
+ * name: randomId('s_'),  // → 's_keeoaui1ubi'
+ * name: randomId('v_'),  // → 'v_a8f3kp2x9qm'
+ * name: randomId(),      // → 'a8f3kp2x9qm'
+ * ```
+ *
+ * Not cryptographically secure — uses `Math.random()`. Good enough for
+ * unique form names / schema keys, NOT for security tokens.
+ */
+export function randomId(prefix = '', length = 11): string {
+  let id = '';
+  for (let i = 0; i < length; i++) {
+    id += CHARSET[(Math.random() * CHARSET.length) | 0];
+  }
+  return `${prefix}${id}`;
+}

package/src/utils/runjsTemplateCompat.ts

@@ -553,8 +553,8 @@ function extractUsedCtxLibKeys(code: string): string[] {
 }
 
 function injectEnsureLibsPreamble(code: string): string {
-  if (!CTX_LIBS_MARKER_RE.test(code)) return code;
   if (ENSURE_LIBS_MARKER_RE.test(code)) return code;
+  if (!CTX_LIBS_MARKER_RE.test(code)) return code;
   const keys = extractUsedCtxLibKeys(code);
   if (!keys.length) return code;
   return `/* __runjs_ensure_libs */\nawait ctx.__ensureLibs(${JSON.stringify(keys)});\n${code}`;

package/src/utils/runjsValue.ts

@@ -236,6 +236,37 @@ function normalizeSubPath(raw: string): { subPath: string; wildcard: boolean } {
   return { subPath: s, wildcard: false };
 }
 
+function extractCtxRootUsage(expr: string): { varName: string; subPath: string; wildcard: boolean } | null {
+  const raw = String(expr || '').trim();
+  if (!raw || raw === 'ctx') return null;
+
+  const dotMatch = raw.match(/^ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)([\s\S]*)$/);
+  if (dotMatch) {
+    const varName = dotMatch[1] || '';
+    const rest = dotMatch[2] || '';
+    const normalized = normalizeSubPath(rest);
+    return {
+      varName,
+      subPath: normalized.subPath,
+      wildcard: normalized.wildcard,
+    };
+  }
+
+  const bracketMatch = raw.match(/^ctx\s*\[\s*(['"])([a-zA-Z_$][a-zA-Z0-9_$]*)\1\s*\]([\s\S]*)$/);
+  if (bracketMatch) {
+    const varName = bracketMatch[2] || '';
+    const rest = bracketMatch[3] || '';
+    const normalized = normalizeSubPath(rest);
+    return {
+      varName,
+      subPath: normalized.subPath,
+      wildcard: normalized.wildcard,
+    };
+  }
+
+  return null;
+}
+
 /**
  * Heuristic extraction of ctx variable usage from RunJS code.
  *
@@ -256,27 +287,35 @@ export function extractUsedVariablePathsFromRunJS(code: string): Record<string,
     usage.set(varName, set);
   };
 
+  const addCtxUsage = (expr: string) => {
+    const hit = extractCtxRootUsage(expr);
+    if (!hit?.varName) return;
+    add(hit.varName, hit.wildcard ? '' : hit.subPath);
+  };
+
   // dot form: ctx.foo.bar / ctx.foo[0].bar (excluding ctx.method(...))
   const dotRe = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*(?:(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)|(?:\[[^\]]+\]))*)(?!\s*\()/g;
   let match: RegExpExecArray | null;
   while ((match = dotRe.exec(src))) {
-    const pathAfterCtx = match[1] || '';
-    const firstKeyMatch = pathAfterCtx.match(/^([a-zA-Z_$][a-zA-Z0-9_$]*)/);
-    if (!firstKeyMatch) continue;
-    const firstKey = firstKeyMatch[1];
-    const rest = pathAfterCtx.slice(firstKey.length);
-    const { subPath, wildcard } = normalizeSubPath(rest);
-    add(firstKey, wildcard ? '' : subPath);
+    addCtxUsage(`ctx.${match[1] || ''}`);
   }
 
   // bracket root: ctx['foo'].bar / ctx["foo"][0] (excluding ctx['method'](...))
   const bracketRootRe =
     /ctx\s*\[\s*(['"])([a-zA-Z_$][a-zA-Z0-9_$]*)\1\s*\]((?:(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)|(?:\[[^\]]+\]))*)(?!\s*\()/g;
   while ((match = bracketRootRe.exec(srcWithStrings))) {
-    const varName = match[2] || '';
-    const rest = match[3] || '';
-    const { subPath, wildcard } = normalizeSubPath(rest);
-    add(varName, wildcard ? '' : subPath);
+    addCtxUsage(`ctx['${match[2] || ''}']${match[3] || ''}`);
+  }
+
+  // async-safe helper form: await ctx.getVar('ctx.foo.bar')
+  const getVarRe = /ctx\.getVar\s*\(\s*(['"])((?:\\.|(?!\1)[\s\S])*)\1\s*\)/g;
+  while ((match = getVarRe.exec(srcWithStrings))) {
+    const expr = String(match[2] || '')
+      .replace(/\\'/g, "'")
+      .replace(/\\"/g, '"')
+      .trim();
+    if (!expr.startsWith('ctx')) continue;
+    addCtxUsage(expr);
   }
 
   const out: Record<string, string[]> = {};

package/src/utils/schema-utils.ts

@@ -11,7 +11,7 @@ import type { ISchema } from '@formily/json-schema';
 import { Schema } from '@formily/json-schema';
 import type { FlowModel } from '../models';
 import { FlowRuntimeContext } from '../flowContext';
-import type { StepDefinition, StepUIMode } from '../types';
+import type { EventDefinition, StepDefinition, StepUIMode } from '../types';
 import { setupRuntimeContextSteps } from './setupRuntimeContextSteps';
 
 /**
@@ -242,6 +242,35 @@ export async function resolveStepUiSchema<TModel extends FlowModel = FlowModel>(
   return resolvedStepUiSchema;
 }
 
+/**
+ * 判断事件在设置菜单中是否应被隐藏。
+ * - 支持 EventDefinition.hideInSettings。
+ * - hideInSettings 可为布尔值或函数（接收 FlowRuntimeContext）。
+ */
+export async function shouldHideEventInSettings<TModel extends FlowModel = FlowModel>(
+  model: TModel,
+  flow: any,
+  event: EventDefinition<TModel> | undefined,
+): Promise<boolean> {
+  if (!event) return true;
+
+  const { hideInSettings } = event;
+
+  if (typeof hideInSettings === 'function') {
+    try {
+      const ctx = new FlowRuntimeContext(model, flow.key, 'settings');
+      setupRuntimeContextSteps(ctx, flow.steps || {}, model, flow.key);
+      const result = await hideInSettings(ctx as any);
+      return !!result;
+    } catch (error) {
+      console.warn(`Error evaluating hideInSettings for event '${event.name || ''}' in flow '${flow.key}':`, error);
+      return false;
+    }
+  }
+
+  return !!hideInSettings;
+}
+
 /**
  * 判断步骤在设置菜单中是否应被隐藏。
  * - 支持 StepDefinition.hideInSettings 与 ActionDefinition.hideInSettings（step 优先）。

package/src/views/FlowView.tsx

@@ -11,13 +11,23 @@ import { PopoverProps as AntdPopoverProps } from 'antd';
 import { FlowContext } from '../flowContext';
 import { ViewNavigation } from './ViewNavigation';
 
+export type FlowViewBeforeClosePayload = {
+  result?: any;
+  force?: boolean;
+};
+
+export type FlowViewBeforeCloseHandler = (
+  payload: FlowViewBeforeClosePayload,
+) => Promise<boolean | void> | boolean | void;
+
 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;
+  close: (result?: any, force?: boolean) => Promise<boolean | void> | boolean | void;
   update: (newConfig: any) => void;
+  beforeClose?: FlowViewBeforeCloseHandler;
   navigation?: ViewNavigation;
   /** 页面的销毁方法 */
   destroy?: () => void;
@@ -74,11 +84,21 @@ export class FlowViewer {
     if (this.types[type]) {
       zIndex += 1;
       const onClose = others.onClose;
+      let zIndexReleased = false;
+      const releaseZIndex = () => {
+        if (!zIndexReleased) {
+          zIndexReleased = true;
+          zIndex -= 1;
+        }
+      };
       const _zIndex = others.zIndex;
       others.onClose = (...args) => {
         onClose?.(...args);
-        zIndex -= 1;
+        releaseZIndex();
       };
+      if (type === 'embed') {
+        others.onOpenCancelled = releaseZIndex;
+      }
       // embed 不能设置过高的 zIndex，会遮挡菜单的折叠按钮图表
       if (type !== 'embed') {
         others.zIndex = _zIndex ?? this.getNextZIndex();

package/src/views/PageComponent.tsx

@@ -24,6 +24,7 @@ export const PageComponent = forwardRef((props: any, ref) => {
     title: _title,
     styles = {},
     zIndex = 4, // 这个默认值是为了防止表格的阴影显示到子页面上面
+    onClose,
   } = mergedProps;
   const closedRef = useRef(false);
   const flowEngine = useFlowEngine();
@@ -86,10 +87,12 @@ export const PageComponent = forwardRef((props: any, ref) => {
             type="text"
             size="small"
             icon={<CloseOutlined />}
-            onClick={() => {
+            onClick={async () => {
               if (!closedRef.current) {
-                closedRef.current = true;
-                props.onClose?.();
+                const closed = await onClose?.();
+                if (closed !== false) {
+                  closedRef.current = true;
+                }
               }
             }}
             style={{
@@ -111,7 +114,7 @@ export const PageComponent = forwardRef((props: any, ref) => {
         {extra && <div>{extra}</div>}
       </div>
     );
-  }, [header, _title, flowEngine.context.themeToken, styles.header, props.onClose]);
+  }, [header, _title, flowEngine.context.themeToken, styles.header, onClose]);
 
   // Footer 组件
   const FooterComponent = useMemo(() => {

package/src/views/ViewNavigation.ts

@@ -13,6 +13,16 @@ import { ViewParam as SharedViewParam } from '../utils';
 
 type ViewParams = Omit<SharedViewParam, 'viewUid'> & { viewUid?: string };
 
+export interface GeneratePathnameFromViewParamsOptions {
+  prefix?: string;
+  basePath?: string;
+}
+
+export interface ViewNavigationOptions {
+  basePath?: string;
+  layoutBasePath?: string;
+}
+
 function encodeFilterByTk(val: SharedViewParam['filterByTk']): string {
   if (val === undefined || val === null) return '';
   // 1.x 兼容：对象按 key1=v1&key2=v2 拼接后整体 encodeURIComponent
@@ -26,6 +36,15 @@ function encodeFilterByTk(val: SharedViewParam['filterByTk']): string {
   return encodeURIComponent(String(val));
 }
 
+function hasUsableSourceId(sourceId: unknown): sourceId is string | number {
+  return sourceId !== undefined && sourceId !== null && String(sourceId) !== '';
+}
+
+function normalizeBasePath(basePath?: string) {
+  const value = basePath || '/admin';
+  return `/${value.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+}
+
 /**
  * 将 ViewParam 数组转换为 pathname
  *
@@ -39,12 +58,17 @@ function encodeFilterByTk(val: SharedViewParam['filterByTk']): string {
  * generatePathnameFromViewParams([{ viewUid: 'xxx' }, { viewUid: 'yyy' }]) // '/admin/xxx/view/yyy'
  * ```
  */
-export function generatePathnameFromViewParams(viewParams: ViewParams[]): string {
+export function generatePathnameFromViewParams(
+  viewParams: ViewParams[],
+  options: GeneratePathnameFromViewParamsOptions = {},
+): string {
+  const basePath = normalizeBasePath(options.basePath || options.prefix);
+
   if (!viewParams || viewParams.length === 0) {
-    return '/admin';
+    return basePath;
   }
 
-  const segments = ['admin'];
+  const segments = basePath.replace(/^\/+/, '').split('/').filter(Boolean);
 
   viewParams.forEach((viewParam, index) => {
     // 如果不是第一个视图，添加 'view' 关键字
@@ -65,8 +89,8 @@ export function generatePathnameFromViewParams(viewParams: ViewParams[]): string
         segments.push('filterbytk', encoded);
       }
     }
-    if (viewParam.sourceId) {
-      segments.push('sourceid', viewParam.sourceId);
+    if (hasUsableSourceId(viewParam.sourceId)) {
+      segments.push('sourceid', String(viewParam.sourceId));
     }
   });
 
@@ -77,10 +101,12 @@ export class ViewNavigation {
   viewStack: ReadonlyArray<ViewParams>; // 只能通过 setViewStack 修改
   ctx: FlowEngineContext;
   viewParams: ViewParams;
+  private readonly basePath?: string;
 
-  constructor(ctx: FlowEngineContext, viewParams: ViewParams[]) {
+  constructor(ctx: FlowEngineContext, viewParams: ViewParams[], options: ViewNavigationOptions = {}) {
     this.setViewStack(viewParams);
     this.ctx = ctx;
+    this.basePath = options.basePath || options.layoutBasePath;
 
     define(this, {
       viewParams: observable,
@@ -102,7 +128,7 @@ export class ViewNavigation {
     });
 
     // 2. 根据 viewStack 生成新的 pathname
-    const newPathname = generatePathnameFromViewParams(newViewStack);
+    const newPathname = generatePathnameFromViewParams(newViewStack, { basePath: this.getLayoutBasePath() });
 
     // 3. 触发一次跳转。使用 replace 的方式
     this.ctx.router.navigate(newPathname, { replace: true });
@@ -111,7 +137,9 @@ export class ViewNavigation {
   navigateTo(viewParam: ViewParams, opts?: { replace?: boolean; state?: any }) {
     // 1. 基于当前 viewStack 生成一个 pathname
     // 2. 将当前传入的参数转为 path string
-    const newViewPathname = generatePathnameFromViewParams([...this.viewStack, viewParam]);
+    const newViewPathname = generatePathnameFromViewParams([...this.viewStack, viewParam], {
+      basePath: this.getLayoutBasePath(),
+    });
 
     // 3. 与 pathname 拼接成新的 pathname（这里直接使用新生成的 pathname）
     const newPathname = newViewPathname;
@@ -122,7 +150,16 @@ export class ViewNavigation {
 
   back() {
     const prevStack = this.viewStack.slice(0, -1);
-    const prevPath = generatePathnameFromViewParams(prevStack);
+    const prevPath = generatePathnameFromViewParams(prevStack, { basePath: this.getLayoutBasePath() });
     this.ctx.router.navigate(prevPath, { replace: true });
   }
+
+  private getLayoutBasePath() {
+    const routePath = (this.ctx as any).layout?.routePath;
+    return (
+      this.basePath ||
+      (this.ctx as any).layoutRoute?.basePathname ||
+      (routePath?.startsWith('/') ? routePath : '/admin')
+    );
+  }
 }