@nocobase/flow-engine 2.1.0-alpha.40 → 2.1.0-alpha.46

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/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/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/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
@@ -30,6 +40,11 @@ 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
  *
@@ -43,12 +58,17 @@ function hasUsableSourceId(sourceId: unknown): sourceId is string | number {
  * 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' 关键字
@@ -81,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,
@@ -106,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 });
@@ -115,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;
@@ -126,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')
+    );
+  }
 }

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

@@ -146,6 +146,47 @@ describe('ViewNavigation', () => {
 
       expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin', { replace: true });
     });
+
+    it('should use explicit basePath when navigating back', () => {
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }], { basePath: '/embed' });
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/embed', { replace: true });
+    });
+
+    it('should use layout route basePathname when explicit basePath is absent', () => {
+      mockCtx.layoutRoute = {
+        basePathname: '/mobile',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/mobile', { replace: true });
+    });
+
+    it('should fall back to layout routePath when explicit basePath is absent', () => {
+      mockCtx.layout = {
+        routePath: '/mobile',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/mobile', { replace: true });
+    });
+
+    it('should ignore relative layout routePath when runtime basePathname is absent', () => {
+      mockCtx.layout = {
+        routePath: 'public-forms',
+      };
+      viewNavigation = new ViewNavigation(mockCtx, [{ viewUid: 'view1' }]);
+
+      viewNavigation.back();
+
+      expect(mockCtx.router.navigate).toHaveBeenCalledWith('/admin', { replace: true });
+    });
   });
 });
 
@@ -160,6 +201,17 @@ describe('generatePathnameFromViewParams', () => {
     expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');
   });
 
+  it('should generate path with custom prefix', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }], { basePath: '/embed' })).toBe('/embed/xxx');
+    expect(generatePathnameFromViewParams([], { basePath: '/embed' })).toBe('/embed');
+  });
+
+  it('should generate path with nested basePath', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }], { basePath: '/admin/settings/public-forms' })).toBe(
+      '/admin/settings/public-forms/xxx',
+    );
+  });
+
   it('should generate view with tab', () => {
     expect(generatePathnameFromViewParams([{ viewUid: 'xxx', tabUid: 'yyy' }])).toBe('/admin/xxx/tab/yyy');
   });

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

@@ -0,0 +1,53 @@
+/**
+ * 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 } from 'vitest';
+import { FlowContext } from '../../flowContext';
+import { inheritLayoutContextForDetachedView } from '../inheritLayoutContext';
+
+describe('inheritLayoutContextForDetachedView', () => {
+  it('inherits layout context for detached view contexts', () => {
+    const sourceContext = new FlowContext();
+    const engineContext = new FlowContext();
+    const layoutContext = new FlowContext();
+    const viewContext = new FlowContext();
+
+    engineContext.defineProperty('skipAclCheck', { value: false });
+    layoutContext.defineProperty('skipAclCheck', { value: true });
+    sourceContext.defineProperty('engine', {
+      value: {
+        context: engineContext,
+      },
+    });
+    sourceContext.defineProperty('layoutContext', { value: layoutContext });
+
+    viewContext.addDelegate(engineContext);
+    inheritLayoutContextForDetachedView(viewContext, sourceContext);
+
+    expect(viewContext.skipAclCheck).toBe(true);
+  });
+
+  it('does nothing when source context has no layout context', () => {
+    const sourceContext = new FlowContext();
+    const engineContext = new FlowContext();
+    const viewContext = new FlowContext();
+
+    engineContext.defineProperty('skipAclCheck', { value: false });
+    sourceContext.defineProperty('engine', {
+      value: {
+        context: engineContext,
+      },
+    });
+
+    viewContext.addDelegate(engineContext);
+    inheritLayoutContextForDetachedView(viewContext, sourceContext);
+
+    expect(viewContext.skipAclCheck).toBe(false);
+  });
+});