@nocobase/plugin-flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.11

package/dist/ai/docs/runjs/context/view.md

@@ -0,0 +1,131 @@
+# ctx.view
+
+The currently active view controller (dialog, drawer, popover, embedded area, etc.), used to access view-level information and operations. Provided by `FlowViewContext`, it is only available within view content opened via `ctx.viewer` or `ctx.openView`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Dialog/Drawer Content** | Use `ctx.view.close()` within the `content` to close the current view, or use `Header` and `Footer` to render titles and footers. |
+| **After Form Submission** | Call `ctx.view.close(result)` after a successful submission to close the view and return the result. |
+| **JSBlock / Action** | Determine the current view type via `ctx.view.type`, or read opening parameters from `ctx.view.inputArgs`. |
+| **Association Selection, Sub-tables** | Read `collectionName`, `filterByTk`, `parentId`, etc., from `inputArgs` for data loading. |
+
+> Note: `ctx.view` is only available in RunJS environments with a view context (e.g., inside the `content` of `ctx.viewer.dialog()`, in dialog forms, or inside association selectors). In standard pages or backend contexts, it is `undefined`. It is recommended to use optional chaining (`ctx.view?.close?.()`).
+
+## Type Definition
+
+```ts
+type FlowView = {
+  type: 'drawer' | 'popover' | 'dialog' | 'embed';
+  inputArgs: Record<string, 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>;  // Available in workflow configuration views
+};
+```
+
+## Common Properties and Methods
+
+| Property/Method | Type | Description |
+|-----------|------|------|
+| `type` | `'drawer' \| 'popover' \| 'dialog' \| 'embed'` | Current view type |
+| `inputArgs` | `Record<string, any>` | Parameters passed when opening the view (see below) |
+| `Header` | `React.FC \| null` | Header component, used to render titles and action areas |
+| `Footer` | `React.FC \| null` | Footer component, used to render buttons, etc. |
+| `close(result?, force?)` | `void` | Closes the current view; `result` can be passed back to the caller |
+| `update(newConfig)` | `void` | Updates view configuration (e.g., width, title) |
+| `navigation` | `ViewNavigation \| undefined` | In-page view navigation, including Tab switching, etc. |
+
+> Currently, only `dialog` and `drawer` support `Header` and `Footer`.
+
+## Common inputArgs Fields
+
+The fields in `inputArgs` vary depending on the opening scenario. Common fields include:
+
+| Field | Description |
+|------|------|
+| `viewUid` | View UID |
+| `collectionName` | Collection name |
+| `filterByTk` | Primary key filter (for single record details) |
+| `parentId` | Parent ID (for association scenarios) |
+| `sourceId` | Source record ID |
+| `parentItem` | Parent item data |
+| `scene` | Scene (e.g., `create`, `edit`, `select`) |
+| `onChange` | Callback after selection or change |
+| `tabUid` | Current Tab UID (within a page) |
+
+Access these via `ctx.getVar('ctx.view.inputArgs.xxx')` or `ctx.view.inputArgs.xxx`.
+
+## Examples
+
+### Closing the Current View
+
+```ts
+// Close dialog after successful submission
+await ctx.resource.runAction('create', { data: formData });
+ctx.view?.close();
+
+// Close and return results
+ctx.view?.close({ id: newRecord.id, name: newRecord.name });
+```
+
+### Using Header / Footer in Content
+
+```tsx
+function DialogContent() {
+  const ctx = useFlowViewContext();
+  const { Header, Footer, close } = ctx.view;
+  return (
+    <div>
+      <Header title="Edit" extra={<Button size="small">Help</Button>} />
+      <div>Form content...</div>
+      <Footer>
+        <Button onClick={() => close()}>Cancel</Button>
+        <Button type="primary" onClick={handleSubmit}>Submit</Button>
+      </Footer>
+    </div>
+  );
+}
+```
+
+### Branching Based on View Type or inputArgs
+
+```ts
+if (ctx.view?.type === 'embed') {
+  // Hide header in embedded views
+  ctx.model.setProps('headerStyle', { display: 'none' });
+}
+
+const collectionName = ctx.view?.inputArgs?.collectionName;
+if (collectionName === 'users') {
+  // User selector scenario
+}
+```
+
+## Relationship with ctx.viewer and ctx.openView
+
+| Purpose | Recommended Usage |
+|------|----------|
+| **Open a new view** | `ctx.viewer.dialog()` / `ctx.viewer.drawer()` or `ctx.openView()` |
+| **Operate on current view** | `ctx.view.close()`, `ctx.view.update()` |
+| **Get opening parameters** | `ctx.view.inputArgs` |
+
+`ctx.viewer` is responsible for "opening" a view, while `ctx.view` represents the "current" view instance. `ctx.openView` is used to open pre-configured workflow views.
+
+## Notes
+
+- `ctx.view` is only available inside a view; it is `undefined` on standard pages.
+- Use optional chaining: `ctx.view?.close?.()` to avoid errors when no view context exists.
+- The `result` from `close(result)` is passed to the Promise returned by `ctx.viewer.open()`.
+
+## Related
+
+- [ctx.openView()](./open-view.md): Open a pre-configured workflow view
+- [ctx.modal](./modal.md): Lightweight popups (info, confirmation, etc.)
+
+> `ctx.viewer` provides methods like `dialog()`, `drawer()`, `popover()`, and `embed()` to open views. The `content` opened by these methods can access `ctx.view`.

package/dist/ai/docs/runjs/document.md

@@ -0,0 +1 @@
+Please provide the Chinese source text you would like me to translate. I am ready to apply all the rules and terminology specified in your instructions.

package/dist/ai/docs/runjs/import-modules.md

@@ -0,0 +1,110 @@
+# Importing Modules
+
+In RunJS, you can use two types of modules: **Built-in modules** (accessed directly via `ctx.libs` without importing) and **External modules** (loaded on demand via `ctx.importAsync()` or `ctx.requireAsync()`).
+
+---
+
+## Built-in Modules - ctx.libs (No import required)
+
+RunJS includes several built-in libraries that can be accessed directly through `ctx.libs`. You **do not** need to use `import` or asynchronous loading for these.
+
+| Property | Description |
+|------|------|
+| **ctx.libs.React** | React core, used for JSX and Hooks |
+| **ctx.libs.ReactDOM** | ReactDOM (can be used for `createRoot`, etc.) |
+| **ctx.libs.antd** | Ant Design component library |
+| **ctx.libs.antdIcons** | Ant Design icons |
+| **ctx.libs.math** | [Math.js](https://mathjs.org/): Mathematical expressions, matrix operations, etc. |
+| **ctx.libs.formula** | [Formula.js](https://formulajs.github.io/): Excel-like formulas (SUM, AVERAGE, etc.) |
+
+### Example: React and antd
+
+```tsx
+const { Button } = ctx.libs.antd;
+
+ctx.render(<Button>Click Me</Button>);
+```
+
+### Example: ctx.libs.math
+
+```ts
+const result = ctx.libs.math.evaluate('2 + 3 * 4');
+// result === 14
+```
+
+### Example: ctx.libs.formula
+
+```ts
+const values = [1, 2, 3, 4];
+const sum = ctx.libs.formula.SUM(values);
+const avg = ctx.libs.formula.AVERAGE(values);
+```
+
+---
+
+## External Modules
+
+When you need third-party libraries, choose the loading method based on the module format:
+
+- **ESM Modules** → Use `ctx.importAsync()`
+- **UMD/AMD Modules** → Use `ctx.requireAsync()`
+
+---
+
+### Importing ESM Modules
+
+Use **`ctx.importAsync()`** to dynamically load ESM modules by URL. This is suitable for scenarios like JS blocks, JS fields, and JS actions.
+
+```ts
+importAsync<T = any>(url: string): Promise<T>;
+```
+
+- **url**: The ESM module address. Supports shorthand formats like `<package>@<version>` or subpaths like `<package>@<version>/<file-path>` (e.g., `vue@3.4.0`, `lodash@4/lodash.js`). These will be prefixed with the configured CDN base URL. Full URLs are also supported.
+- **Returns**: The resolved module namespace object.
+
+#### Default: https://esm.sh
+
+If not configured otherwise, shorthand forms will use **https://esm.sh** as the CDN prefix. For example:
+
+```ts
+const Vue = await ctx.importAsync('vue@3.4.0');
+// Equivalent to loading from https://esm.sh/vue@3.4.0
+```
+
+#### Self-hosted esm.sh Service
+
+If you need to use an internal network or a self-built CDN, you can deploy a service compatible with the esm.sh protocol and specify it via environment variables:
+
+- **ESM_CDN_BASE_URL**: The base URL for the ESM CDN (defaults to `https://esm.sh`)
+- **ESM_CDN_SUFFIX**: Optional suffix (e.g., `/+esm` for jsDelivr)
+
+For self-hosting, refer to: [https://github.com/nocobase/esm-server](https://github.com/nocobase/esm-server)
+
+---
+
+### Importing UMD/AMD Modules
+
+Use **`ctx.requireAsync()`** to asynchronously load UMD/AMD modules or scripts that attach to the global object.
+
+```ts
+requireAsync<T = any>(url: string): Promise<T>;
+```
+
+- **url**: Supports two forms:
+  - **Shorthand path**: `<package>@<version>/<file-path>`, similar to `ctx.importAsync()`, resolved according to the current ESM CDN configuration. When resolving, `?raw` is appended to request the raw file directly (usually a UMD build). For example, `echarts@5/dist/echarts.min.js` actually requests `https://esm.sh/echarts@5/dist/echarts.min.js?raw` (when using the default esm.sh).
+  - **Full URL**: Any full CDN address (e.g., `https://cdn.jsdelivr.net/npm/xxx`).
+- **Returns**: The loaded library object (the specific form depends on how the library exports its content).
+
+After loading, many UMD libraries attach themselves to the global object (e.g., `window.xxx`). You can use them as described in the library's documentation.
+
+**Example**
+
+```ts
+// Shorthand path (resolved via esm.sh as ...?raw)
+const echarts = await ctx.requireAsync('echarts@5/dist/echarts.min.js');
+
+// Full URL
+const dayjs = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
+```
+
+**Note**: If a library provides an ESM version, prefer using `ctx.importAsync()` for better module semantics and Tree-shaking.

package/dist/ai/docs/runjs/index.md

@@ -0,0 +1,65 @@
+# RunJS Overview
+
+RunJS is the JavaScript execution environment used in NocoBase for scenarios such as **JS Blocks**, **JS Fields**, and **JS Actions**. Code runs in a restricted sandbox, providing safe access to the `ctx` (Context API) and includes the following capabilities:
+
+- Top-level `await`
+- Importing external modules
+- Rendering within containers
+- Global variables
+
+## Top-level await
+
+RunJS supports top-level `await`, eliminating the need to wrap code in an IIFE.
+
+**Not Recommended**
+
+```jsx
+async function test() {}
+(async () => {
+  await test();
+})();
+```
+
+**Recommended**
+
+```js
+async function test() {}
+await test();
+```
+
+## Importing External Modules
+
+- Use `ctx.importAsync()` for ESM modules (Recommended)
+- Use `ctx.requireAsync()` for UMD/AMD modules
+
+## Rendering within Containers
+
+Use `ctx.render()` to render content into the current container (`ctx.element`). It supports the following three formats:
+
+### Rendering JSX
+
+```jsx
+ctx.render(<button>Button</button>);
+```
+
+### Rendering DOM Nodes
+
+```js
+const div = document.createElement('div');
+div.innerHTML = 'Hello World';
+
+ctx.render(div);
+```
+
+### Rendering HTML Strings
+
+```js
+ctx.render('<h1>Hello World</h1>');
+```
+
+## Global Variables
+
+- `window`
+- `document`
+- `navigator`
+- `ctx`

package/dist/ai/docs/runjs/jsx.md

@@ -0,0 +1,84 @@
+# JSX
+
+RunJS supports JSX syntax, allowing you to write code similar to React components. JSX is automatically compiled before execution.
+
+## Compilation Notes
+
+- Uses [sucrase](https://github.com/alangpierce/sucrase) to transform JSX.
+- JSX is compiled into `ctx.libs.React.createElement` and `ctx.libs.React.Fragment`.
+- **No need to import React**: You can write JSX directly; it will automatically use `ctx.libs.React` after compilation.
+- When loading external React via `ctx.importAsync('react@x.x.x')`, JSX will switch to using the `createElement` method from that specific instance.
+
+## Using Built-in React and Components
+
+RunJS includes React and common UI libraries built-in. You can access them directly via `ctx.libs` without using `import`:
+
+- **ctx.libs.React** — React core
+- **ctx.libs.ReactDOM** — ReactDOM (can be used with `createRoot` if needed)
+- **ctx.libs.antd** — Ant Design components
+- **ctx.libs.antdIcons** — Ant Design icons
+
+```tsx
+const { Button } = ctx.libs.antd;
+
+ctx.render(<Button>Click</Button>);
+```
+
+When writing JSX directly, you don't need to destructure React. You only need to destructure from `ctx.libs` when using **Hooks** (such as `useState`, `useEffect`) or **Fragment** (`<>...</>`):
+
+```tsx
+const { React } = ctx.libs;
+const { useState } = React;
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+  return <div>Count: {count}</div>;
+};
+
+ctx.render(<Counter />);
+```
+
+**Note**: Built-in React and external React imported via `ctx.importAsync()` **cannot be mixed**. If you use an external UI library, React must also be imported from the same external source.
+
+## Using External React and Components
+
+When loading a specific version of React and UI libraries via `ctx.importAsync()`, JSX will use that React instance:
+
+```tsx
+const React = await ctx.importAsync('react@19.2.4');
+const { Button } = await ctx.importAsync('antd@6.2.2?bundle');
+
+ctx.render(<Button>Click</Button>);
+```
+
+If antd depends on react/react-dom, you can specify the same version via `deps` to avoid multiple instances:
+
+```tsx
+const React = await ctx.importAsync('react@18.2.0');
+const { Button } = await ctx.importAsync('antd@5.29.3?bundle&deps=react@18.2.0,react-dom@18.2.0');
+
+ctx.render(<Button>Button</Button>);
+```
+
+**Note**: When using external React, UI libraries like antd must also be imported via `ctx.importAsync()`. Do not mix them with `ctx.libs.antd`.
+
+## JSX Syntax Key Points
+
+- **Components and props**: `<Button type="primary">Text</Button>`
+- **Fragment**: `<>...</>` or `<React.Fragment>...</React.Fragment>` (requires destructuring `const { React } = ctx.libs` when using Fragment)
+- **Expressions**: Use `{expression}` in JSX to insert variables or operations, such as `{ctx.user.name}` or `{count + 1}`. Do not use `{{ }}` template syntax.
+- **Conditional Rendering**: `{flag && <span>Content</span>}` or `{flag ? <A /> : <B />}`
+- **List Rendering**: Use `array.map()` to return a list of elements, and ensure each element has a stable `key`.
+
+```tsx
+const { React } = ctx.libs;
+const items = ['a', 'b', 'c'];
+
+ctx.render(
+  <ul>
+    {items.map((item, i) => (
+      <li key={i}>{item}</li>
+    ))}
+  </ul>
+);
+```

package/dist/ai/docs/runjs/model/form-block-model.md

@@ -0,0 +1 @@
+# FormBlockModel

package/dist/ai/docs/runjs/render.md

@@ -0,0 +1,64 @@
+# In-container Rendering
+
+Use `ctx.render()` to render content into the current container (`ctx.element`). It supports the following three forms:
+
+## `ctx.render()`
+
+### Rendering JSX
+
+```jsx
+ctx.render(<button>Button</button>);
+```
+
+### Rendering DOM Nodes
+
+```js
+const div = document.createElement('div');
+div.innerHTML = 'Hello World';
+ctx.render(div);
+```
+
+### Rendering HTML Strings
+
+```js
+ctx.render('<h1>Hello World</h1>');
+```
+
+## JSX Description
+
+RunJS can render JSX directly. You can use the built-in React/component libraries or load external dependencies on demand.
+
+### Using Built-in React and Component Libraries
+
+```jsx
+const { Button } = ctx.libs.antd;
+
+ctx.render(<Button>Click</Button>);
+```
+
+### Using External React and Component Libraries
+
+Load specific versions on demand via `ctx.importAsync()`:
+
+```jsx
+const React = await ctx.importAsync('react@19.2.4');
+const { Button } = await ctx.importAsync('antd@6.2.2?bundle');
+
+ctx.render(<Button>Click</Button>);
+```
+
+Suitable for scenarios requiring specific versions or third-party components.
+
+## ctx.element
+
+Not recommended (deprecated):
+
+```js
+ctx.element.innerHTML = '<h1>Hello World</h1>';
+```
+
+Recommended way:
+
+```js
+ctx.render(<h1>Hello World</h1>);
+```

package/dist/ai/docs/runjs/resource/api-resource.md

@@ -0,0 +1,155 @@
+# APIResource
+
+A **generic API resource** for making requests based on URLs, suitable for any HTTP interface. It inherits from the `FlowResource` base class and extends it with request configuration and `refresh()`. Unlike [MultiRecordResource](./multi-record-resource.md) and [SingleRecordResource](./single-record-resource.md), `APIResource` does not depend on a resource name; it requests directly by URL, making it suitable for custom interfaces, third-party APIs, and other scenarios.
+
+**Creation method**: `ctx.makeResource('APIResource')` or `ctx.initResource('APIResource')`. You must call `setURL()` before use. In the RunJS context, `ctx.api` (APIClient) is automatically injected, so there is no need to call `setAPIClient` manually.
+
+---
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Custom Interface** | Call non-standard resource APIs (e.g., `/api/custom/stats`, `/api/reports/summary`). |
+| **Third-party API** | Request external services via full URL (requires CORS support from the target). |
+| **One-time Query** | Temporary data fetching that is disposable and does not need to be bound to `ctx.resource`. |
+| **Choosing between APIResource and ctx.request** | Use `APIResource` when reactive data, events, or error states are needed; use `ctx.request()` for simple one-time requests. |
+
+---
+
+## Base Class Capabilities (FlowResource)
+
+All Resources possess the following:
+
+| Method | Description |
+|------|------|
+| `getData()` | Get current data. |
+| `setData(value)` | Set data (local only). |
+| `hasData()` | Whether data exists. |
+| `getMeta(key?)` / `setMeta(meta)` | Read/write metadata. |
+| `getError()` / `setError(err)` / `clearError()` | Error state management. |
+| `on(event, callback)` / `once` / `off` / `emit` | Event subscription and triggering. |
+
+---
+
+## Request Configuration
+
+| Method | Description |
+|------|------|
+| `setAPIClient(api)` | Set the APIClient instance (usually automatically injected in RunJS). |
+| `getURL()` / `setURL(url)` | Request URL. |
+| `loading` | Read/write loading state (get/set). |
+| `clearRequestParameters()` | Clear request parameters. |
+| `setRequestParameters(params)` | Merge and set request parameters. |
+| `setRequestMethod(method)` | Set request method (e.g., `'get'`, `'post'`, default is `'get'`). |
+| `addRequestHeader(key, value)` / `removeRequestHeader(key)` | Request headers. |
+| `addRequestParameter(key, value)` / `getRequestParameter(key)` / `removeRequestParameter(key)` | Add, delete, or query a single parameter. |
+| `setRequestBody(data)` | Request body (used for POST/PUT/PATCH). |
+| `setRequestOptions(key, value)` / `getRequestOptions()` | General request options. |
+
+---
+
+## URL Format
+
+- **Resource Style**: Supports NocoBase resource shorthand, such as `users:list` or `posts:get`, which will be concatenated with the `baseURL`.
+- **Relative Path**: e.g., `/api/custom/endpoint`, concatenated with the application's `baseURL`.
+- **Full URL**: Use full addresses for cross-origin requests; the target must have CORS configured.
+
+---
+
+## Data Fetching
+
+| Method | Description |
+|------|------|
+| `refresh()` | Initiates a request based on the current URL, method, params, headers, and data. It writes the response `data` into `setData(data)` and triggers the `'refresh'` event. On failure, it sets `setError(err)` and throws a `ResourceError`, without triggering the `refresh` event. Requires `api` and URL to be set. |
+
+---
+
+## Examples
+
+### Basic GET Request
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('/api/custom/endpoint');
+res.setRequestParameters({ page: 1, pageSize: 10 });
+await res.refresh();
+const data = res.getData();
+```
+
+### Resource Style URL
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('users:list');
+res.setRequestParameters({ pageSize: 20, sort: ['-createdAt'] });
+await res.refresh();
+const rows = res.getData()?.data ?? [];
+```
+
+### POST Request (with Request Body)
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('/api/custom/submit');
+res.setRequestMethod('post');
+res.setRequestBody({ name: 'test', type: 'report' });
+await res.refresh();
+const result = res.getData();
+```
+
+### Listening to the refresh Event
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('/api/stats');
+res.on('refresh', () => {
+  const data = res.getData();
+  ctx.render(<div>Stats: {JSON.stringify(data)}</div>);
+});
+await res.refresh();
+```
+
+### Error Handling
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('/api/may-fail');
+try {
+  await res.refresh();
+  const data = res.getData();
+} catch (e) {
+  const err = res.getError();
+  ctx.message.error(err?.message ?? 'Request failed');
+}
+```
+
+### Custom Request Headers
+
+```js
+const res = ctx.makeResource('APIResource');
+res.setURL('https://api.example.com/data');
+res.addRequestHeader('X-Custom-Header', 'value');
+res.addRequestParameter('key', 'xxx');
+await res.refresh();
+```
+
+---
+
+## Notes
+
+- **ctx.api Dependency**: In RunJS, `ctx.api` is injected by the environment; manual `setAPIClient` is usually unnecessary. If used in a context-less scenario, you must set it yourself.
+- **Refresh Means Request**: `refresh()` initiates a request based on the current configuration; method, params, data, etc., must be configured before calling.
+- **Errors Do Not Update Data**: On failure, `getData()` keeps its previous value; error information can be retrieved via `getError()`.
+- **Vs ctx.request**: Use `ctx.request()` for simple one-time requests; use `APIResource` when reactive data, events, and error state management are required.
+
+---
+
+## Related
+
+- [ctx.resource](../context/resource.md) - The resource instance in the current context
+- [ctx.initResource()](../context/init-resource.md) - Initialize and bind to `ctx.resource`
+- [ctx.makeResource()](../context/make-resource.md) - Create a new resource instance without binding
+- [ctx.request()](../context/request.md) - General HTTP request, suitable for simple one-time calls
+- [MultiRecordResource](./multi-record-resource.md) - For Collections/lists, supports CRUD and pagination
+- [SingleRecordResource](./single-record-resource.md) - For single records