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

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

@@ -0,0 +1,110 @@
+# Import Modules
+
+In RunJS you can use two kinds of modules: **built-in modules** (via `ctx.libs`, no import needed) and **external modules** (loaded on demand via `ctx.importAsync()` or `ctx.requireAsync()`).
+
+---
+
+## Built-in Modules - ctx.libs (no import)
+
+RunJS provides common libraries via `ctx.libs`; you can use them directly **without** `import` or async loading.
+
+| Property | Description |
+|----------|-------------|
+| **ctx.libs.React** | React core for JSX and Hooks |
+| **ctx.libs.ReactDOM** | ReactDOM (e.g. for createRoot) |
+| **ctx.libs.antd** | Ant Design components |
+| **ctx.libs.antdIcons** | Ant Design icons |
+| **ctx.libs.math** | [Math.js](https://mathjs.org/): math 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</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
+
+For third-party libraries, choose the loader by module format:
+
+- **ESM** → use `ctx.importAsync()`
+- **UMD/AMD** → use `ctx.requireAsync()`
+
+---
+
+### Import ESM Modules
+
+Use **`ctx.importAsync()`** to load ESM modules by URL at runtime. Suitable for JS Block, JS Field, JS Action, etc.
+
+```ts
+importAsync<T = any>(url: string): Promise<T>;
+```
+
+- **url**: ESM module URL. Supports shorthand `<package>@<version>` or subpath `<package>@<version>/<path>` (e.g. `vue@3.4.0`, `lodash@4/lodash.js`), which is resolved with the configured CDN prefix; full URLs are also supported.
+- **Returns**: The resolved module namespace object.
+
+#### Default: https://esm.sh
+
+When not configured, the shorthand form uses **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
+
+For intranet or custom CDN, deploy an esm.sh-compatible service and set:
+
+- **ESM_CDN_BASE_URL**: ESM CDN base URL (default `https://esm.sh`)
+- **ESM_CDN_SUFFIX**: Optional suffix (e.g. jsDelivr’s `/+esm`)
+
+Reference: [https://github.com/nocobase/esm-server](https://github.com/nocobase/esm-server)
+
+---
+
+### Import UMD/AMD Modules
+
+Use **`ctx.requireAsync()`** to load UMD/AMD scripts or scripts that attach to the global object by URL.
+
+```ts
+requireAsync<T = any>(url: string): Promise<T>;
+```
+
+- **url**: Either:
+  - **Shorthand path**: `<package>@<version>/<path>`, same as `ctx.importAsync()`; resolved with the current ESM CDN config; `?raw` is appended to request the raw file (usually UMD). E.g. `echarts@5/dist/echarts.min.js` becomes `https://esm.sh/echarts@5/dist/echarts.min.js?raw` when using default esm.sh.
+  - **Full URL**: Any CDN URL (e.g. `https://cdn.jsdelivr.net/npm/xxx`).
+- **Returns**: The loaded library object (shape depends on the library’s exports).
+
+Many UMD libraries attach to the global (e.g. `window.xxx`); use them as documented.
+
+**Example**
+
+```ts
+// Shorthand (resolved via esm.sh with ...?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 both ESM and UMD, prefer `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 in NocoBase used for **JS Block**, **JS Field**, **JS Action**, and similar scenarios. Code runs in a restricted sandbox with safe access to the `ctx` (context API) and supports:
+
+- Top-level `await`
+- Importing external modules
+- Render in container
+- Global variables
+
+## Top-level `await`
+
+RunJS supports top-level `await`; you do not 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
+
+- ESM modules: use `ctx.importAsync()` (recommended)
+- UMD/AMD modules: use `ctx.requireAsync()`
+
+## Render in Container
+
+Use `ctx.render()` to render content into the current container (`ctx.element`) in three ways:
+
+### Render JSX
+
+```jsx
+ctx.render(<button>Button</button>);
+```
+
+### Render DOM Node
+
+```js
+const div = document.createElement('div');
+div.innerHTML = 'Hello World';
+
+ctx.render(div);
+```
+
+### Render HTML String
+
+```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; you can write code like React components, and JSX is compiled before execution.
+
+## Compilation
+
+- JSX is transformed with [sucrase](https://github.com/alangpierce/sucrase)
+- JSX compiles to `ctx.libs.React.createElement` and `ctx.libs.React.Fragment`
+- **No need to import React**: write JSX directly; the compiler uses `ctx.libs.React`
+- When loading external React via `ctx.importAsync('react@x.x.x')`, JSX uses that instance’s `createElement`
+
+## Using Built-in React and Components
+
+RunJS includes React and common UI libraries; use them via `ctx.libs` without `import`:
+
+- **ctx.libs.React** — React core
+- **ctx.libs.ReactDOM** — ReactDOM (e.g. for createRoot)
+- **ctx.libs.antd** — Ant Design components
+- **ctx.libs.antdIcons** — Ant Design icons
+
+```tsx
+const { Button } = ctx.libs.antd;
+
+ctx.render(<Button>Click</Button>);
+```
+
+You don’t need to destructure React for plain JSX; destructure from `ctx.libs` only when using **Hooks** (e.g. `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 React loaded via `ctx.importAsync()` **must not be mixed**. If you use an external UI library, import React from the same external source.
+
+## Using External React and Components
+
+When you load React and a UI library with `ctx.importAsync()`, JSX uses 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, use `deps` to pin the same version and 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**: With external React, load antd and other UI libraries via `ctx.importAsync()`; do not mix with `ctx.libs.antd`.
+
+## JSX Basics
+
+- **Components and props**: `<Button type="primary">Text</Button>`
+- **Fragment**: `<>...</>` or `<React.Fragment>...</React.Fragment>` (destructure `const { React } = ctx.libs` when using Fragment)
+- **Expressions**: Use `{expression}` in JSX for variables or expressions, e.g. `{ctx.user.name}`, `{count + 1}`; do not use `{{ }}` template syntax
+- **Conditional render**: `{flag && <span>Content</span>}` or `{flag ? <A /> : <B />}`
+- **List render**: Use `array.map()` and give each element 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,3 @@
+# FormBlockModel
+
+Form block model: the block model type for form blocks (Form, EditForm, etc.). In RunJS, when the current JS runs inside a form block, `ctx.blockModel` is often a FormBlockModel (or EditFormModel). See [ctx.blockModel](../context/block-model.md) and [ctx.form](../context/form.md) for usage.

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

@@ -0,0 +1,64 @@
+# Render in Container
+
+Use `ctx.render()` to render content into the current container (`ctx.element`) in three ways:
+
+## ctx.render()
+
+### Render JSX
+
+```jsx
+ctx.render(<button>Button</button>);
+```
+
+### Render DOM Node
+
+```js
+const div = document.createElement('div');
+div.innerHTML = 'Hello World';
+ctx.render(div);
+```
+
+### Render HTML String
+
+```js
+ctx.render('<h1>Hello World</h1>');
+```
+
+## JSX Notes
+
+RunJS can render JSX directly, using either the built-in React/component library or externally loaded dependencies.
+
+### Using Built-in React and Components
+
+```jsx
+const { Button } = ctx.libs.antd;
+
+ctx.render(<Button>Click</Button>);
+```
+
+### Using External React and Components
+
+Load a specific version 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>);
+```
+
+Use this when you need a specific version or third-party components.
+
+## ctx.element
+
+**Not recommended** (deprecated):
+
+```js
+ctx.element.innerHTML = '<h1>Hello World</h1>';
+```
+
+**Recommended**:
+
+```js
+ctx.render(<h1>Hello World</h1>);
+```

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

@@ -0,0 +1,155 @@
+# APIResource
+
+Generic **API resource** that sends requests by URL; use for any HTTP endpoint. Extends FlowResource with request config and `refresh()`. Unlike [MultiRecordResource](./multi-record-resource.md) and [SingleRecordResource](./single-record-resource.md), APIResource does not depend on resource name and requests directly by URL; suitable for custom endpoints, third-party APIs, etc.
+
+**Create with**: `ctx.makeResource('APIResource')` or `ctx.initResource('APIResource')`. Before use call `setURL()`; RunJS context auto-injects `ctx.api` (APIClient), no need to call `setAPIClient` manually.
+
+---
+
+## Use cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Custom endpoints** | Call non-standard resource APIs (e.g. `/api/custom/stats`, `/api/reports/summary`) |
+| **Third-party APIs** | Request external services via full URL (target must support CORS) |
+| **One-off queries** | Fetch data temporarily, no need to bind to `ctx.resource` |
+| **vs ctx.request** | Use APIResource when you need reactive data, events, or error state; use `ctx.request()` for simple one-off requests |
+
+---
+
+## Base (FlowResource)
+
+All resources support:
+
+| Method | Description |
+|--------|-------------|
+| `getData()` | 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 |
+| `on(event, callback)` / `once` / `off` / `emit` | Subscribe and emit events |
+
+---
+
+## Request config
+
+| Method | Description |
+|--------|-------------|
+| `setAPIClient(api)` | Set APIClient instance (RunJS usually injects via context) |
+| `getURL()` / `setURL(url)` | Request URL |
+| `loading` | Load state (get/set) |
+| `clearRequestParameters()` | Clear request params |
+| `setRequestParameters(params)` | Merge request params |
+| `setRequestMethod(method)` | Method (e.g. `'get'`, `'post'`, default `'get'`) |
+| `addRequestHeader(key, value)` / `removeRequestHeader(key)` | Headers |
+| `addRequestParameter(key, value)` / `getRequestParameter(key)` / `removeRequestParameter(key)` | Single param add/get/remove |
+| `setRequestBody(data)` | Request body (for POST/PUT/PATCH) |
+| `setRequestOptions(key, value)` / `getRequestOptions()` | General request options |
+
+---
+
+## URL format
+
+- **Resource style**: NocoBase shorthand supported, e.g. `users:list`, `posts:get`, concatenated with baseURL
+- **Relative path**: e.g. `/api/custom/endpoint`, concatenated with app baseURL
+- **Full URL**: Use full address for cross-origin; target must configure CORS
+
+---
+
+## Data fetch
+
+| Method | Description |
+|--------|-------------|
+| `refresh()` | Send request with current URL, method, params, headers, data; write response `data` to `setData(data)` and emit `'refresh'`. On failure sets `setError(err)` and throws `ResourceError`, does not emit `refresh`. Requires `api` and URL. |
+
+---
+
+## 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 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();
+```
+
+### Listen to 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 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**: RunJS injects `ctx.api`; usually no need to call `setAPIClient`. Set it manually when used without context.
+- **refresh = request**: `refresh()` sends one request with current config; method, params, data, etc. must be set before calling.
+- **Error does not update data**: On failure `getData()` keeps previous value; use `getError()` for error info.
+- **vs ctx.request**: Use `ctx.request()` for simple one-off requests; use APIResource when you need reactive data, events, or error state management.
+
+---
+
+## Related
+
+- [ctx.resource](../context/resource.md) - Resource instance in current context
+- [ctx.initResource()](../context/init-resource.md) - Initialize and bind to ctx.resource
+- [ctx.makeResource()](../context/make-resource.md) - Create resource instance without binding
+- [ctx.request()](../context/request.md) - Generic HTTP request, for simple one-off calls
+- [MultiRecordResource](./multi-record-resource.md) - For data tables/lists, CRUD, pagination
+- [SingleRecordResource](./single-record-resource.md) - For single records

package/dist/ai/docs/runjs/resource/multi-record-resource.md

@@ -0,0 +1,188 @@
+# MultiRecordResource
+
+Resource for **data tables/lists**: request returns an array; supports pagination, filter, sort, and CRUD. Use for tables, lists, and other "multiple records" scenarios. Unlike [APIResource](./api-resource.md), MultiRecordResource uses `setResourceName()` to specify resource name and auto-builds URLs like `users:list`, `users:create`, with built-in pagination, filter, and selected rows.
+
+**Inheritance**: FlowResource → APIResource → BaseRecordResource → MultiRecordResource.
+
+**Create with**: `ctx.makeResource('MultiRecordResource')` or `ctx.initResource('MultiRecordResource')`. Before use call `setResourceName('collectionName')` (e.g. `'users'`); RunJS injects `ctx.api`.
+
+---
+
+## Use cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Table block** | Table and list blocks use MultiRecordResource by default; pagination, filter, sort |
+| **JSBlock list** | Load users, orders, etc. in JSBlock and render custom UI |
+| **Batch operations** | Use `getSelectedRows()` for selected rows, `destroySelectedRows()` for batch delete |
+| **Association resources** | Load associated data with `users.tags`; requires `setSourceId(parentRecordId)` |
+
+---
+
+## Data format
+
+- `getData()` returns a **record array**, i.e. the list API `data` field
+- `getMeta()` returns pagination meta: `page`, `pageSize`, `count`, `totalPage`, etc.
+
+---
+
+## Resource name and data source
+
+| Method | Description |
+|--------|-------------|
+| `setResourceName(name)` / `getResourceName()` | Resource name, e.g. `'users'`, `'users.tags'` (association) |
+| `setSourceId(id)` / `getSourceId()` | Parent record id for association resources (e.g. `users.tags` needs users primary key) |
+| `setDataSourceKey(key)` / `getDataSourceKey()` | Data source key (for multiple data sources) |
+
+---
+
+## Request params (filter / fields / sort)
+
+| Method | Description |
+|--------|-------------|
+| `setFilterByTk(tk)` / `getFilterByTk()` | Primary key filter (single get, etc.) |
+| `setFilter(filter)` / `getFilter()` / `resetFilter()` | Filter; supports `$eq`, `$ne`, `$in`, etc. |
+| `addFilterGroup(key, filter)` / `removeFilterGroup(key)` | Filter groups (combine conditions) |
+| `setFields(fields)` / `getFields()` | Requested fields (whitelist) |
+| `setSort(sort)` / `getSort()` | Sort, e.g. `['-createdAt']` for created-at desc |
+| `setAppends(appends)` / `getAppends()` / `addAppends` / `removeAppends` | Association expansion (e.g. `['user', 'tags']`) |
+
+---
+
+## Pagination
+
+| Method | Description |
+|--------|-------------|
+| `setPage(page)` / `getPage()` | Current page (1-based) |
+| `setPageSize(size)` / `getPageSize()` | Page size, default 20 |
+| `getTotalPage()` | Total pages |
+| `getCount()` | Total count (from server meta) |
+| `next()` / `previous()` / `goto(page)` | Change page and trigger refresh |
+
+---
+
+## Selected rows (table)
+
+| Method | Description |
+|--------|-------------|
+| `setSelectedRows(rows)` / `getSelectedRows()` | Currently selected row data for batch delete, etc. |
+
+---
+
+## CRUD and list operations
+
+| Method | Description |
+|--------|-------------|
+| `refresh()` | Request list with current params; update `getData()` and pagination meta; emit `'refresh'` |
+| `get(filterByTk)` | Request single record; returns that record (does not write to getData) |
+| `create(data, options?)` | Create; optional `{ refresh: false }` to skip auto refresh; emit `'saved'` |
+| `update(filterByTk, data, options?)` | Update by primary key |
+| `destroy(target)` | Delete; target can be primary key, row object, or array (batch delete) |
+| `destroySelectedRows()` | Delete selected rows (throws if none selected) |
+| `setItem(index, item)` | Replace one row locally (no request) |
+| `runAction(actionName, options)` | Call any resource action (e.g. custom action) |
+
+---
+
+## Config and events
+
+| Method | Description |
+|--------|-------------|
+| `setRefreshAction(name)` | Action used for refresh; default `'list'` |
+| `setCreateActionOptions(options)` / `setUpdateActionOptions(options)` | Request config for create/update |
+| `on('refresh', fn)` / `on('saved', fn)` | Fired when refresh completes or after save |
+
+---
+
+## Examples
+
+### Basic list
+
+```js
+ctx.initResource('MultiRecordResource');
+ctx.resource.setResourceName('users');
+ctx.resource.setPageSize(20);
+await ctx.resource.refresh();
+const rows = ctx.resource.getData();
+const total = ctx.resource.getCount();
+```
+
+### Filter and sort
+
+```js
+ctx.resource.setResourceName('users');
+ctx.resource.setFilter({ status: 'active' });
+ctx.resource.setSort(['-createdAt']);
+ctx.resource.setFields(['id', 'nickname', 'email']);
+await ctx.resource.refresh();
+```
+
+### Association expansion
+
+```js
+ctx.resource.setResourceName('orders');
+ctx.resource.setAppends(['user', 'items']);
+await ctx.resource.refresh();
+const orders = ctx.resource.getData();
+```
+
+### Create and pagination
+
+```js
+await ctx.resource.create({ name: 'John', email: 'john@example.com' });
+
+await ctx.resource.next();
+await ctx.resource.previous();
+await ctx.resource.goto(3);
+```
+
+### Batch delete selected rows
+
+```js
+const rows = ctx.resource?.getSelectedRows?.() || [];
+if (rows.length === 0) {
+  ctx.message.warning('Please select data first');
+  return;
+}
+await ctx.resource.destroySelectedRows();
+ctx.message.success(ctx.t('Deleted'));
+```
+
+### Listen to refresh event
+
+```js
+ctx.resource?.on?.('refresh', () => {
+  const data = ctx.resource.getData();
+  ctx.render(<ul>{data?.map((r) => <li key={r.id}>{r.name}</li>)}</ul>);
+});
+await ctx.resource?.refresh?.();
+```
+
+### Association resource (child table)
+
+```js
+const res = ctx.makeResource('MultiRecordResource');
+res.setResourceName('users.roles');
+res.setSourceId(ctx.record?.id);
+await res.refresh();
+const roles = res.getData();
+```
+
+---
+
+## Notes
+
+- **setResourceName required**: Must call `setResourceName('collectionName')` before use; otherwise request URL cannot be built.
+- **Association resources**: When resource name is `parent.child` (e.g. `users.tags`), call `setSourceId(parentPrimaryKey)` first.
+- **refresh debounce**: Multiple `refresh()` calls in the same event loop only run the last one to avoid duplicate requests.
+- **getData is array**: List API returns `data` as record array; `getData()` returns that array directly.
+
+---
+
+## Related
+
+- [ctx.resource](../context/resource.md) - Resource instance in current context
+- [ctx.initResource()](../context/init-resource.md) - Initialize and bind to ctx.resource
+- [ctx.makeResource()](../context/make-resource.md) - Create resource instance without binding
+- [APIResource](./api-resource.md) - Generic API resource, request by URL
+- [SingleRecordResource](./single-record-resource.md) - For single records