@nocobase/flow-engine 2.0.0-beta.13 → 2.0.0-beta.14

package/src/__tests__/runjsLibsLazyLoading.test.ts

@@ -0,0 +1,44 @@
+/**
+ * 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, it, expect } from 'vitest';
+import { FlowEngine } from '../flowEngine';
+import { registerRunJSLib } from '../runjsLibs';
+
+describe('RunJS ctx.libs lazy loading', () => {
+  it('preloads member access via prepareRunJsCode injection', async () => {
+    registerRunJSLib('testLib', async () => ({ foo: 123 }));
+
+    const engine = new FlowEngine();
+    const ctx: any = engine.context;
+    const r = await ctx.runjs(`return ctx.libs.testLib.foo;`);
+    expect(r.success).toBe(true);
+    expect(r.value).toBe(123);
+  });
+
+  it('preloads bracket access via prepareRunJsCode injection', async () => {
+    registerRunJSLib('testLib', async () => ({ foo: 456 }));
+
+    const engine = new FlowEngine();
+    const ctx: any = engine.context;
+    const r = await ctx.runjs(`return ctx.libs['testLib'].foo;`);
+    expect(r.success).toBe(true);
+    expect(r.value).toBe(456);
+  });
+
+  it('preloads object destructuring via prepareRunJsCode injection', async () => {
+    registerRunJSLib('testLib', async () => ({ foo: 789 }));
+
+    const engine = new FlowEngine();
+    const ctx: any = engine.context;
+    const r = await ctx.runjs(`const { testLib } = ctx.libs; return testLib.foo;`);
+    expect(r.success).toBe(true);
+    expect(r.value).toBe(789);
+  });
+});

package/src/flowContext.ts

@@ -13,7 +13,6 @@ import { APIClient } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
 import { MessageInstance } from 'antd/es/message/interface';
 import * as antd from 'antd';
-import * as antdIcons from '@ant-design/icons';
 import type { HookAPI } from 'antd/es/modal/useModal';
 import { NotificationInstance } from 'antd/es/notification/interface';
 import _ from 'lodash';
@@ -51,6 +50,7 @@ import { FlowView, FlowViewer } from './views/FlowView';
 import { RunJSContextRegistry, getModelClassName } from './runjs-context/registry';
 import { createEphemeralContext } from './utils/createEphemeralContext';
 import dayjs from 'dayjs';
+import { setupRunJSLibs } from './runjsLibs';
 
 // Helper: detect a RecordRef-like object
 function isRecordRefLike(val: any): boolean {
@@ -1829,6 +1829,7 @@ function __runjsDeepMerge(base: any, patch: any) {
   }
   return out;
 }
+
 export class FlowRunJSContext extends FlowContext {
   constructor(delegate: FlowContext) {
     super();
@@ -1849,17 +1850,7 @@ export class FlowRunJSContext extends FlowContext {
     };
     this.defineProperty('ReactDOM', { value: ReactDOMShim });
 
-    // 为第三方/通用库提供统一命名空间：ctx.libs
-    // - 新增库应优先挂载到 ctx.libs.xxx
-    // - 同时保留顶层别名（如 ctx.React / ctx.antd），以兼容历史代码
-    const libs = Object.freeze({
-      React,
-      ReactDOM: ReactDOMShim,
-      antd,
-      dayjs,
-      antdIcons,
-    });
-    this.defineProperty('libs', { value: libs });
+    setupRunJSLibs(this);
 
     // Convenience: ctx.render(<App />[, container])
     // - container defaults to ctx.element if available

package/src/flowSettings.ts

@@ -32,6 +32,7 @@ import {
   shouldHideStepInSettings,
 } from './utils';
 import { FlowStepContext } from './hooks/useFlowStep';
+import { GLOBAL_EMBED_CONTAINER_ID, EMBED_REPLACING_DATA_KEY } from './views';
 
 const Panel = Collapse.Panel;
 
@@ -682,14 +683,10 @@ export class FlowSettings {
       typeof resolvedUiMode === 'object' && resolvedUiMode ? resolvedUiMode.props || {} : {};
 
     if (modeType === 'embed') {
-      const target = document.querySelector<HTMLDivElement>('#nocobase-embed-container');
+      const target = document.querySelector<HTMLDivElement>(`#${GLOBAL_EMBED_CONTAINER_ID}`);
       const onOpen = modeProps.onOpen;
       const onClose = modeProps.onClose;
 
-      if (target) {
-        target.innerHTML = ''; // 清空容器内原有内容
-      }
-
       modeProps = {
         target,
         styles: {
@@ -699,15 +696,19 @@ export class FlowSettings {
         },
         ...modeProps,
         onOpen() {
-          target.style.width = modeProps.width || '33.3%';
-          target.style.maxWidth = modeProps.maxWidth || '800px';
-          target.style.minWidth = modeProps.minWidth || '0px';
+          if (target) {
+            target.style.width = modeProps.width || '33.3%';
+            target.style.maxWidth = modeProps.maxWidth || '800px';
+            target.style.minWidth = modeProps.minWidth || '0px';
+          }
           onOpen?.();
         },
         onClose() {
-          target.style.width = 'auto';
-          target.style.maxWidth = 'none';
-          target.style.minWidth = 'auto';
+          if (target && target.dataset[EMBED_REPLACING_DATA_KEY] !== '1') {
+            target.style.width = 'auto';
+            target.style.maxWidth = 'none';
+            target.style.minWidth = 'auto';
+          }
           onClose?.();
         },
       };

package/src/index.ts

@@ -13,6 +13,8 @@ export * from './types';
 // 工具函数
 export * from './utils';
 export { compileRunJs } from './utils/jsxTransform';
+export { registerRunJSLib } from './runjsLibs';
+export type { RunJSLibCache, RunJSLibLoader } from './runjsLibs';
 
 // 资源类
 export * from './resources';

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

@@ -50,7 +50,8 @@ export function defineBaseContextMeta() {
         'ReactDOM client API including createRoot for rendering React components. Also available via `ctx.libs.ReactDOM`.',
       antd: 'Ant Design component library. Recommended access path: `ctx.libs.antd`.',
       libs: {
-        description: 'Namespace for third-party and shared libraries. Includes React, ReactDOM, Ant Design, and dayjs.',
+        description:
+          'Namespace for third-party and shared libraries. Includes React, ReactDOM, Ant Design, dayjs, lodash, math.js, and formula.js.',
         detail: 'Libraries namespace',
         properties: {
           React: 'React namespace (same as ctx.React).',
@@ -58,6 +59,9 @@ export function defineBaseContextMeta() {
           antd: 'Ant Design component library (same as ctx.antd).',
           dayjs: 'dayjs date-time utility library.',
           antdIcons: 'Ant Design icons library. Example: `ctx.libs.antdIcons.PlusOutlined`.',
+          lodash: 'Lodash utility library. Example: `ctx.libs.lodash.get(obj, "a.b.c")`.',
+          math: 'Math.js library for mathematical operations. Example: `ctx.libs.math.evaluate("2 + 3 * 4")`.',
+          formula: 'Formula.js library for spreadsheet-like formulas. Example: `ctx.libs.formula.SUM([1, 2, 3])`.',
         },
       },
     },
@@ -147,7 +151,7 @@ export function defineBaseContextMeta() {
         antd: 'Ant Design 组件库（RunJS 环境中可用）。推荐使用 `ctx.libs.antd` 访问。',
         libs: {
           description:
-            '第三方/通用库的统一命名空间，包含 React、ReactDOM、Ant Design、dayjs 等。后续新增库会优先挂在此处。',
+            '第三方/通用库的统一命名空间，包含 React、ReactDOM、Ant Design、dayjs、lodash、math.js、formula.js 等。后续新增库会优先挂在此处。',
           detail: '通用库命名空间',
           properties: {
             React: 'React 命名空间（等价于 ctx.React）。',
@@ -155,6 +159,9 @@ export function defineBaseContextMeta() {
             antd: 'Ant Design 组件库（等价于 ctx.antd）。',
             dayjs: 'dayjs 日期时间工具库。',
             antdIcons: 'Ant Design 图标库。 例如：`ctx.libs.antdIcons.PlusOutlined`。',
+            lodash: 'Lodash 工具库。例如：`ctx.libs.lodash.get(obj, "a.b.c")`。',
+            math: 'Math.js 数学运算库。例如：`ctx.libs.math.evaluate("2 + 3 * 4")`。',
+            formula: 'Formula.js 电子表格公式库。例如：`ctx.libs.formula.SUM([1, 2, 3])`。',
           },
         },
       },

package/src/runjsLibs.ts

@@ -0,0 +1,218 @@
+/**
+ * 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 antdIcons from '@ant-design/icons';
+import type { FlowContext } from './flowContext';
+
+export type RunJSLibCache = 'global' | 'context';
+export type RunJSLibLoader<T = any> = (ctx: FlowContext) => T | Promise<T>;
+
+type RunJSLibRegistryEntry = {
+  loader: RunJSLibLoader<unknown>;
+  cache: RunJSLibCache;
+};
+
+const __runjsLibRegistry = new Map<string, RunJSLibRegistryEntry>();
+
+const __runjsLibResolvedCache = new Map<string, unknown>();
+const __runjsLibPendingCache = new Map<string, Promise<unknown>>();
+const __runjsLibPendingByCtx = new WeakMap<FlowContext, Map<string, Promise<unknown>>>();
+
+function __runjsGetPendingMapForCtx(ctx: FlowContext): Map<string, Promise<unknown>> {
+  let m = __runjsLibPendingByCtx.get(ctx);
+  if (!m) {
+    m = new Map<string, Promise<unknown>>();
+    __runjsLibPendingByCtx.set(ctx, m);
+  }
+  return m;
+}
+
+export function registerRunJSLib(name: string, loader: RunJSLibLoader, options?: { cache?: RunJSLibCache }): void {
+  if (typeof name !== 'string' || !name) return;
+  if (typeof loader !== 'function') return;
+  __runjsLibRegistry.set(name, { loader, cache: options?.cache || 'global' });
+  // allow re-register to take effect on next ensure
+  __runjsLibResolvedCache.delete(name);
+  __runjsLibPendingCache.delete(name);
+}
+
+function __runjsIsObject(val: unknown): val is Record<string, unknown> {
+  return !!val && typeof val === 'object';
+}
+
+function __runjsHasOwn(obj: unknown, key: string): obj is Record<string, unknown> {
+  return __runjsIsObject(obj) && Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function __runjsIsPromiseLike(val: unknown): val is PromiseLike<unknown> {
+  if (!__runjsIsObject(val)) return false;
+  const then = (val as { then?: unknown }).then;
+  return typeof then === 'function';
+}
+
+function __runjsGetCtxValue(ctx: FlowContext, key: string): unknown {
+  return (ctx as unknown as Record<string, unknown>)[key];
+}
+
+async function __runjsEnsureLib(ctx: FlowContext, name: string): Promise<unknown> {
+  const libs = (ctx as unknown as { libs?: unknown })?.libs;
+  if (__runjsHasOwn(libs, name)) {
+    const existing = libs[name];
+    if (typeof existing !== 'undefined') return existing;
+  }
+
+  const entry = __runjsLibRegistry.get(name);
+  if (!entry) return __runjsIsObject(libs) ? libs[name] : undefined;
+
+  const setLib = (v: unknown) => {
+    if (__runjsIsObject(libs)) libs[name] = v;
+  };
+
+  if (entry.cache === 'context') {
+    const pendingMap = __runjsGetPendingMapForCtx(ctx);
+    const existingPending = pendingMap.get(name);
+    if (existingPending) {
+      const v = await existingPending;
+      setLib(v);
+      return v;
+    }
+
+    const task = Promise.resolve()
+      .then(() => entry.loader(ctx))
+      .then(
+        (v) => {
+          pendingMap.delete(name);
+          return v;
+        },
+        (err) => {
+          pendingMap.delete(name);
+          throw err;
+        },
+      );
+    pendingMap.set(name, task);
+    const v = await task;
+    setLib(v);
+    return v;
+  }
+
+  if (__runjsLibResolvedCache.has(name)) {
+    const v = __runjsLibResolvedCache.get(name);
+    setLib(v);
+    return v;
+  }
+
+  const existingPending = __runjsLibPendingCache.get(name);
+  if (existingPending) {
+    const v = await existingPending;
+    setLib(v);
+    return v;
+  }
+
+  const task = Promise.resolve()
+    .then(() => entry.loader(ctx))
+    .then(
+      (v) => {
+        __runjsLibResolvedCache.set(name, v);
+        __runjsLibPendingCache.delete(name);
+        return v;
+      },
+      (err) => {
+        __runjsLibPendingCache.delete(name);
+        throw err;
+      },
+    );
+  __runjsLibPendingCache.set(name, task);
+  const v = await task;
+  setLib(v);
+  return v;
+}
+
+function setupRunJSLibAPIs(ctx: FlowContext): void {
+  if (!ctx || typeof ctx !== 'object') return;
+  if (typeof ctx.defineMethod !== 'function') return;
+
+  // Internal: ensure libs are loaded before first use.
+  // NOTE: name with `__` prefix to reduce accidental use; still callable from RunJS.
+  ctx.defineMethod('__ensureLib', async function (this: FlowContext, name: string) {
+    if (typeof name !== 'string' || !name) return undefined;
+    return await __runjsEnsureLib(this, name);
+  });
+  ctx.defineMethod('__ensureLibs', async function (this: FlowContext, names: unknown) {
+    if (!Array.isArray(names)) return;
+    for (const n of names) {
+      if (typeof n !== 'string' || !n) continue;
+      await __runjsEnsureLib(this, n);
+    }
+  });
+}
+
+const DEFAULT_RUNJS_LIBS: Array<{ name: string; cache: RunJSLibCache; loader: RunJSLibLoader }> = [
+  { name: 'React', cache: 'context', loader: (ctx) => __runjsGetCtxValue(ctx, 'React') },
+  { name: 'ReactDOM', cache: 'context', loader: (ctx) => __runjsGetCtxValue(ctx, 'ReactDOM') },
+  { name: 'antd', cache: 'context', loader: (ctx) => __runjsGetCtxValue(ctx, 'antd') },
+  { name: 'dayjs', cache: 'context', loader: (ctx) => __runjsGetCtxValue(ctx, 'dayjs') },
+  { name: 'antdIcons', cache: 'global', loader: () => antdIcons },
+  { name: 'lodash', cache: 'global', loader: () => import('lodash').then((m) => m.default || m) },
+  { name: 'formula', cache: 'global', loader: () => import('@formulajs/formulajs').then((m) => m.default || m) },
+  { name: 'math', cache: 'global', loader: () => import('mathjs').then((m) => m) },
+];
+
+let __defaultRunJSLibsRegistered = false;
+
+function ensureDefaultRunJSLibsRegistered(): void {
+  if (__defaultRunJSLibsRegistered) return;
+  __defaultRunJSLibsRegistered = true;
+  for (const { name, loader, cache } of DEFAULT_RUNJS_LIBS) {
+    if (__runjsLibRegistry.has(name)) continue;
+    registerRunJSLib(name, loader, { cache });
+  }
+}
+
+function resolveRegisteredLibSync(ctx: FlowContext, name: string): unknown {
+  const entry = __runjsLibRegistry.get(name);
+  if (!entry) return undefined;
+  if (entry.cache === 'global' && __runjsLibResolvedCache.has(name)) {
+    return __runjsLibResolvedCache.get(name);
+  }
+  const v = entry.loader(ctx);
+  if (__runjsIsPromiseLike(v)) return undefined;
+  if (entry.cache === 'global') __runjsLibResolvedCache.set(name, v);
+  return v;
+}
+
+export function setupRunJSLibs(ctx: FlowContext): void {
+  if (!ctx || typeof ctx !== 'object') return;
+  if (typeof ctx.defineProperty !== 'function') return;
+
+  ensureDefaultRunJSLibsRegistered();
+
+  // 为第三方/通用库提供统一命名空间：ctx.libs
+  // - 新增库应优先挂载到 ctx.libs.xxx（通过 registerRunJSLib）
+  // - 同时保留顶层别名（如 ctx.React / ctx.antd），以兼容历史代码
+  const libs: Record<string, unknown> = {};
+  for (const { name } of DEFAULT_RUNJS_LIBS) {
+    Object.defineProperty(libs, name, {
+      configurable: true,
+      enumerable: true,
+      get() {
+        const v = resolveRegisteredLibSync(ctx, name);
+        // Lazy materialize as writable data property on first access
+        Object.defineProperty(libs, name, {
+          configurable: true,
+          enumerable: true,
+          writable: true,
+          value: v,
+        });
+        return v;
+      },
+    });
+  }
+  ctx.defineProperty('libs', { value: libs });
+  setupRunJSLibAPIs(ctx);
+}

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

@@ -102,6 +102,39 @@ ctx.render(<div className="x">{name}</div>);
       expect(out).toMatch(/ctx\.resolveJsonTemplate/);
     });
 
+    it('injects ctx.libs ensure preamble for member access', async () => {
+      const src = `return ctx.libs.lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`/* __runjs_ensure_libs */`);
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for bracket access with string literal', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('injects ctx.libs ensure preamble for object destructuring', async () => {
+      const src = `const { lodash } = ctx.libs;\nreturn lodash;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).toContain(`await ctx.__ensureLibs(["lodash"]);`);
+    });
+
+    it('does not inject ctx.libs preamble when ctx.libs only appears in string/comment', async () => {
+      const src = `// ctx.libs.lodash\nconst s = "ctx.libs.lodash";\nreturn s;`;
+      const out = await prepareRunJsCode(src, { preprocessTemplates: false });
+      expect(out).not.toContain(`__runjs_ensure_libs`);
+    });
+
+    it('is idempotent for already-prepared code', async () => {
+      const src = `return ctx.libs['lodash'];`;
+      const out1 = await prepareRunJsCode(src, { preprocessTemplates: false });
+      const out2 = await prepareRunJsCode(out1, { preprocessTemplates: false });
+      expect(out2).toBe(out1);
+      expect(out2.match(/__runjs_ensure_libs/g)?.length ?? 0).toBe(1);
+    });
+
     it('does not break JSX attribute string values when preprocessing templates', async () => {
       const src = `ctx.render(<Input title="{{ctx.user.name}}" />);`;
       const out = await prepareRunJsCode(src, { preprocessTemplates: true });