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

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

@@ -0,0 +1,79 @@
+# ctx.on()
+
+Subscribe to context events in RunJS (e.g. field value change, property change, resource refresh). Events are mapped to custom DOM events on `ctx.element` or the internal event bus on `ctx.resource`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField / JSEditableField** | Sync UI when field value changes from outside (form, linkage); two-way binding |
+| **JSBlock / JSItem / JSColumn** | Listen to custom events on the container; react to data/state changes |
+| **resource** | Listen to refresh, save, etc.; run logic after data updates |
+
+## Type
+
+```ts
+on(eventName: string, handler: (event?: any) => void): void;
+```
+
+## Common Events
+
+| Event | Description | Source |
+|-------|-------------|--------|
+| `js-field:value-change` | Field value changed from outside (form linkage, default value) | CustomEvent on `ctx.element`; `ev.detail` = new value |
+| `resource:refresh` | Resource data refreshed | `ctx.resource` event bus |
+| `resource:saved` | Resource save completed | `ctx.resource` event bus |
+
+> Events with `resource:` prefix use `ctx.resource.on`; others typically use DOM events on `ctx.element` when present.
+
+## Examples
+
+### Two-way binding (React useEffect + cleanup)
+
+```tsx
+React.useEffect(() => {
+  const handler = (ev) => setValue(ev?.detail ?? '');
+  ctx.on?.('js-field:value-change', handler);
+  return () => {
+    ctx.off?.('js-field:value-change', handler);
+  };
+}, []);
+```
+
+### Native DOM when ctx.on not available
+
+```ts
+const handler = (ev) => {
+  if (selectEl) selectEl.value = String(ev?.detail ?? '');
+};
+ctx.element?.addEventListener('js-field:value-change', handler);
+// Cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
+```
+
+### Update UI after resource refresh
+
+```ts
+ctx.resource?.on('refresh', () => {
+  const data = ctx.resource?.getData?.();
+  // Update render from data
+});
+```
+
+## With ctx.off
+
+- Unsubscribe with [ctx.off](./off.md) when appropriate to avoid leaks or duplicate handlers.
+- In React, usually call `ctx.off` in `useEffect` cleanup.
+- `ctx.off` may not exist; use optional chaining: `ctx.off?.('eventName', handler)`.
+
+## Notes
+
+1. **Pair with off**: Each `ctx.on(eventName, handler)` should have a matching `ctx.off(eventName, handler)` with the same `handler` reference.
+2. **Lifecycle**: Remove listeners before unmount or context destroy to avoid leaks.
+3. **Event support**: Different context types support different events; see component docs.
+
+## Related
+
+- [ctx.off](./off.md): remove listener
+- [ctx.element](./element.md): container and DOM events
+- [ctx.resource](./resource.md): resource and its `on`/`off`
+- [ctx.setValue](./set-value.md): sets field value; triggers `js-field:value-change`

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

@@ -0,0 +1,120 @@
+# ctx.openView()
+
+Opens a configured view (drawer, dialog, embed, etc.) programmatically. Provided by FlowModelContext; used in JSBlock, table cells, event flow, etc. to open ChildPage or PopupAction views.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Button opens detail/edit dialog; pass current row `filterByTk` |
+| **Table cell** | Button in cell opens row detail dialog |
+| **Event flow / JSAction** | Open next view or dialog after action success |
+| **Association field** | `ctx.runAction('openView', params)` for select/edit dialog |
+
+> Note: `ctx.openView` requires a FlowModel context; if no model exists for the uid, a PopupActionModel is created and persisted.
+
+## Signature
+
+```ts
+openView(uid: string, options?: OpenViewOptions): Promise<void>
+```
+
+## Parameters
+
+### uid
+
+Unique id of the view model. If missing, it is created and saved. Use a stable uid (e.g. `${ctx.model.uid}-detail`) so the same popup can be reused.
+
+### options (common fields)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | `drawer` / `dialog` / `embed` | How to open: drawer, dialog, embed; default `drawer` |
+| `size` | `small` / `medium` / `large` | Dialog/drawer size; default `medium` |
+| `title` | `string` | View title |
+| `params` | `Record<string, any>` | Arbitrary params passed to the view |
+| `filterByTk` | `any` | Primary key for single-record detail/edit |
+| `sourceId` | `string` | Source record id (associations) |
+| `dataSourceKey` | `string` | Data source |
+| `collectionName` | `string` | Collection name |
+| `associationName` | `string` | Association field name |
+| `navigation` | `boolean` | Use route navigation; forced `false` when passing `defineProperties` / `defineMethods` |
+| `preventClose` | `boolean` | Prevent close |
+| `defineProperties` | `Record<string, PropertyOptions>` | Inject properties into view models |
+| `defineMethods` | `Record<string, Function>` | Inject methods into view models |
+
+## Examples
+
+### Basic: open drawer
+
+```ts
+const popupUid = `${ctx.model.uid}-detail`;
+await ctx.openView(popupUid, {
+  mode: 'drawer',
+  size: 'medium',
+  title: ctx.t('Detail'),
+});
+```
+
+### Pass current row context
+
+```ts
+const primaryKey = ctx.collection?.primaryKey || 'id';
+await ctx.openView(`${ctx.model.uid}-1`, {
+  mode: 'dialog',
+  title: ctx.t('Row detail'),
+  params: {
+    filterByTk: ctx.record?.[primaryKey],
+    record: ctx.record,
+  },
+});
+```
+
+### Open via runAction
+
+When the model has an openView action (e.g. association field, clickable field):
+
+```ts
+await ctx.runAction('openView', {
+  navigation: false,
+  mode: 'dialog',
+  collectionName: 'users',
+  filterByTk: ctx.record?.id,
+});
+```
+
+### Inject custom context
+
+```ts
+await ctx.openView(`${ctx.model.uid}-edit`, {
+  mode: 'drawer',
+  filterByTk: ctx.record?.id,
+  defineProperties: {
+    onSaved: {
+      get: () => () => ctx.resource?.refresh?.(),
+      cache: false,
+    },
+  },
+});
+```
+
+## Relation to ctx.viewer, ctx.view
+
+| Use | Recommended |
+|-----|-------------|
+| **Open configured flow view** | `ctx.openView(uid, options)` |
+| **Open custom content (no flow)** | `ctx.viewer.dialog()` / `ctx.viewer.drawer()` |
+| **Operate current view** | `ctx.view.close()`, `ctx.view.inputArgs` |
+
+`ctx.openView` opens a FlowPage (ChildPageModel) with a full flow; `ctx.viewer` opens arbitrary React content.
+
+## Notes
+
+- Prefer uids related to `ctx.model.uid` (e.g. `${ctx.model.uid}-xxx`) to avoid conflicts between blocks.
+- When passing `defineProperties` / `defineMethods`, `navigation` is forced to `false` so context is not lost on refresh.
+- Inside a popup, `ctx.view` is the current view and `ctx.view.inputArgs` holds the params passed when opening.
+
+## Related
+
+- [ctx.view](./view.md): current view instance
+- [ctx.model](./model.md): current model; use for stable popupUid

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

@@ -0,0 +1,109 @@
+# ctx.render()
+
+Renders a React element, HTML string, or DOM node into a container. Without `container`, renders into `ctx.element` and inherits the app’s ConfigProvider, theme, etc.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Custom block content (charts, lists, cards, etc.) |
+| **JSField / JSItem / JSColumn** | Custom editable field or table column |
+| **Detail block** | Custom detail field display |
+
+> Note: `ctx.render()` needs a container. If you don’t pass `container` and `ctx.element` is missing (e.g. no-UI logic), an error is thrown.
+
+## Type
+
+```ts
+render(
+  vnode: React.ReactElement | Node | DocumentFragment | string,
+  container?: Element | DocumentFragment
+): ReactDOMClient.Root | null;
+```
+
+| Parameter | Type | Description |
+|------------|------|-------------|
+| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to render |
+| `container` | `Element` \| `DocumentFragment` (optional) | Target container; default `ctx.element` |
+
+**Returns**:
+
+- For **React element**: `ReactDOMClient.Root` (for later `root.render()` updates).
+- For **HTML string** or **DOM node**: `null`.
+
+## vnode types
+
+| Type | Behavior |
+|------|----------|
+| `React.ReactElement` (JSX) | Rendered with React `createRoot`; full React; inherits app context |
+| `string` | Sanitized with DOMPurify and set as container `innerHTML`; existing React root is unmounted first |
+| `Node` (Element, Text, etc.) | Container cleared then `appendChild`; existing React root unmounted first |
+| `DocumentFragment` | Fragment children appended to container; existing React root unmounted first |
+
+## Examples
+
+### React (JSX)
+
+```tsx
+const { Button, Card } = ctx.libs.antd;
+
+ctx.render(
+  <Card title={ctx.t('Title')}>
+    <Button type="primary" onClick={() => ctx.message.success(ctx.t('Clicked'))}>
+      {ctx.t('Button')}
+    </Button>
+  </Card>
+);
+```
+
+### HTML string
+
+```ts
+ctx.render('<h1>Hello World</h1>');
+
+ctx.render('<div style="padding:16px">' + ctx.t('Content') + '</div>');
+
+ctx.render(hasData ? `<ul>${items.map(i => `<li>${i}</li>`).join('')}</ul>` : '<span style="color:#999">' + ctx.t('No data') + '</span>');
+```
+
+### DOM node
+
+```ts
+const div = document.createElement('div');
+div.textContent = 'Hello World';
+ctx.render(div);
+
+const container = document.createElement('div');
+container.style.width = '100%';
+container.style.height = '400px';
+ctx.render(container);
+const chart = echarts.init(container);
+chart.setOption({ ... });
+```
+
+### Custom container
+
+```ts
+const customEl = document.getElementById('my-container');
+ctx.render(<div>Content</div>, customEl);
+```
+
+### Multiple calls replace content
+
+```ts
+ctx.render(<div>First</div>);
+ctx.render(<div>Second</div>);  // Only "Second" is shown
+```
+
+## Notes
+
+- **Each call replaces**: Content is replaced, not appended.
+- **HTML safety**: HTML is sanitized with DOMPurify; still avoid concatenating untrusted user input.
+- **Don’t touch ctx.element directly**: `ctx.element.innerHTML` is deprecated; use `ctx.render()`.
+- **No container**: When `ctx.element` is `undefined` (e.g. inside a module loaded by `ctx.importAsync`), pass `container` explicitly.
+
+## Related
+
+- [ctx.element](./element.md): default container when `container` is not passed
+- [ctx.libs](./libs.md): React, antd, etc. for JSX
+- [ctx.importAsync()](./import-async.md): load external React/components then use with `ctx.render()`

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

@@ -0,0 +1,162 @@
+# ctx.request()
+
+Sends authenticated HTTP requests from RunJS. Requests use the app’s baseURL, token, locale, role, etc., and the app’s interceptors and error handling.
+
+## Use Cases
+
+Use whenever RunJS needs to call a remote HTTP API: JSBlock, JSField, JSItem, JSColumn, event flow, linkage, JSAction, etc.
+
+## Type
+
+```typescript
+request(options: RequestOptions): Promise<AxiosResponse<any>>;
+```
+
+`RequestOptions` extends Axios `AxiosRequestConfig`:
+
+```typescript
+type RequestOptions = AxiosRequestConfig & {
+  skipNotify?: boolean | ((error: any) => boolean);  // Skip global error toast on failure
+  skipAuth?: boolean;                                 // Skip auth redirect (e.g. 401 → login)
+};
+```
+
+## Common parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | URL. Supports resource style (e.g. `users:list`, `posts:create`) or full URL |
+| `method` | 'get' \| 'post' \| 'put' \| 'patch' \| 'delete' | HTTP method; default `'get'` |
+| `params` | object | Query params (serialized to URL) |
+| `data` | any | Request body for post/put/patch |
+| `headers` | object | Custom headers |
+| `skipNotify` | boolean \| (error) => boolean | When true or function returns true, no global error message |
+| `skipAuth` | boolean | When true, 401 etc. do not trigger auth redirect (e.g. to login) |
+
+## Resource-style URL
+
+NocoBase resource API supports `resource:action` shorthand:
+
+| Format | Description | Example |
+|--------|-------------|---------|
+| `collection:action` | Single-table CRUD | `users:list`, `users:get`, `users:create`, `posts:update` |
+| `collection.relation:action` | Association (need `resourceOf` or primary key in URL) | `posts.comments:list` |
+
+Relative URLs are joined with the app baseURL (usually `/api`). For cross-origin, use a full URL and ensure CORS on the target.
+
+## Response
+
+Returns Axios response. Common usage:
+
+- `response.data`: response body
+- List APIs often have `data.data` (records) + `data.meta` (pagination)
+- Single/create/update often have `data.data` as one record
+
+## Examples
+
+### List
+
+```javascript
+const { data } = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: { pageSize: 10, page: 1 },
+});
+
+const rows = Array.isArray(data?.data) ? data.data : [];
+const meta = data?.meta;
+```
+
+### Create
+
+```javascript
+const res = await ctx.request({
+  url: 'users:create',
+  method: 'post',
+  data: { nickname: 'John', email: 'john@example.com' },
+});
+
+const newRecord = res?.data?.data;
+```
+
+### Filter and sort
+
+```javascript
+const res = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: {
+    pageSize: 20,
+    sort: ['-createdAt'],
+    filter: { status: 'active' },
+  },
+});
+```
+
+### Skip error notify
+
+```javascript
+const res = await ctx.request({
+  url: 'some:action',
+  method: 'get',
+  skipNotify: true,
+});
+
+const res2 = await ctx.request({
+  url: 'some:action',
+  method: 'get',
+  skipNotify: (err) => err?.name === 'CanceledError',
+});
+```
+
+### Cross-origin
+
+For other domains, the target must allow CORS. For its own token, pass in headers:
+
+```javascript
+const res = await ctx.request({
+  url: 'https://api.example.com/v1/data',
+  method: 'get',
+});
+
+const res2 = await ctx.request({
+  url: 'https://api.other.com/items',
+  method: 'get',
+  headers: {
+    Authorization: 'Bearer <target-token>',
+  },
+});
+```
+
+### With ctx.render
+
+```javascript
+const { data } = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: { pageSize: 5 },
+});
+const rows = Array.isArray(data?.data) ? data.data : [];
+
+ctx.render([
+  '<div style="padding:12px">',
+  '<h4>' + ctx.t('User list') + '</h4>',
+  '<ul>',
+  ...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
+  '</ul>',
+  '</div>',
+].join(''));
+```
+
+## Notes
+
+- **Errors**: Failed requests throw; by default a global error message is shown. Use `skipNotify: true` to handle yourself.
+- **Auth**: Same-origin requests automatically send token, locale, role; cross-origin needs CORS and optional token in headers.
+- **ACL**: Requests are subject to ACL; only resources the user can access are available.
+
+## Related
+
+- [ctx.message](./message.md): short feedback after request
+- [ctx.notification](./notification.md): notification after request
+- [ctx.render](./render.md): render result in UI
+- [ctx.makeResource](./make-resource.md): build resource for chained loading (alternative to direct `ctx.request`)

package/dist/ai/docs/runjs/context/require-async.md

@@ -0,0 +1,107 @@
+# ctx.requireAsync()
+
+Loads **UMD/AMD** or global scripts by URL asynchronously; can also load **CSS**. Use for ECharts, Chart.js, FullCalendar (UMD), jQuery plugins, etc. in RunJS; pass a `.css` URL to load and inject styles. If a library provides ESM, prefer [ctx.importAsync()](./import-async.md).
+
+## Use Cases
+
+Use whenever RunJS needs to load UMD/AMD/global scripts or CSS: JSBlock, JSField, JSItem, JSColumn, event flow, JSAction, etc. Typical: ECharts, Chart.js, FullCalendar (UMD), dayjs (UMD), jQuery plugins.
+
+## Type
+
+```ts
+requireAsync<T = any>(url: string): Promise<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | Script or CSS URL. Supports **shorthand** `<package>@<version>/<path>` (ESM CDN adds `?raw` for raw UMD) or **full URL**. `.css` URLs load and inject styles. |
+
+## Returns
+
+- Loaded library object (first module value from UMD/AMD callback). Many UMD libs attach to `window` (e.g. `window.echarts`); return value may be `undefined`—use the library’s docs for how to access.
+- For `.css` URLs, returns the result of `loadCSS`.
+
+## URL format
+
+- **Shorthand**: e.g. `echarts@5/dist/echarts.min.js`; with default ESM CDN (esm.sh) becomes `https://esm.sh/echarts@5/dist/echarts.min.js?raw`; `?raw` fetches the raw UMD file.
+- **Full URL**: Any CDN URL, e.g. `https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js`.
+- **CSS**: URLs ending in `.css` are loaded and injected.
+
+## vs ctx.importAsync()
+
+- **ctx.requireAsync()**: Loads **UMD/AMD/global** scripts; good for ECharts, Chart.js, FullCalendar (UMD), jQuery plugins; lib often on `window`; return may be the lib or `undefined`.
+- **ctx.importAsync()**: Loads **ESM**; returns module namespace. If a lib has ESM, prefer `ctx.importAsync()` for better module semantics and tree-shaking.
+
+## Examples
+
+### Basic
+
+```javascript
+const echarts = await ctx.requireAsync('echarts@5/dist/echarts.min.js');
+
+const dayjs = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
+
+await ctx.requireAsync('https://cdn.example.com/theme.css');
+```
+
+### ECharts
+
+```javascript
+const container = document.createElement('div');
+container.style.height = '400px';
+container.style.width = '100%';
+ctx.render(container);
+
+const echarts = await ctx.requireAsync('echarts@5/dist/echarts.min.js');
+if (!echarts) throw new Error('ECharts library not loaded');
+
+const chart = echarts.init(container);
+chart.setOption({
+  title: { text: ctx.t('Sales overview') },
+  series: [{ type: 'pie', data: [{ value: 1, name: ctx.t('A') }] }],
+});
+chart.resize();
+```
+
+### Chart.js bar
+
+```javascript
+async function renderChart() {
+  const loaded = await ctx.requireAsync('chart.js@4.4.0/dist/chart.umd.min.js');
+  const Chart = loaded?.Chart || loaded?.default?.Chart || loaded?.default;
+  if (!Chart) throw new Error('Chart.js not loaded');
+
+  const container = document.createElement('canvas');
+  ctx.render(container);
+
+  new Chart(container, {
+    type: 'bar',
+    data: {
+      labels: ['A', 'B', 'C'],
+      datasets: [{ label: ctx.t('Count'), data: [12, 19, 3] }],
+    },
+  });
+}
+await renderChart();
+```
+
+### dayjs (UMD)
+
+```javascript
+const dayjs = await ctx.requireAsync('dayjs@1/dayjs.min.js');
+console.log(dayjs?.default || dayjs);
+```
+
+## Notes
+
+- **Return shape**: UMD libs vary; return may be the lib or `undefined`; if `undefined`, use the lib’s docs (often `window`).
+- **Network**: Requires CDN access; for intranet set **ESM_CDN_BASE_URL** to your own service.
+- **Choice**: If a lib has both ESM and UMD, prefer `ctx.importAsync()`.
+
+## Related
+
+- [ctx.importAsync()](./import-async.md): load ESM; good for Vue, dayjs (ESM), etc.
+- [ctx.render()](./render.md): render charts etc. into container
+- [ctx.libs](./libs.md): built-in React, antd, dayjs; no async load

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

@@ -0,0 +1,92 @@
+# ctx.resource
+
+The **FlowResource** instance in the current context; used to access and operate on data. In most blocks (form, table, detail, etc.) and popups, the runtime binds `ctx.resource`; in JSBlock and similar contexts that have no resource by default, call [ctx.initResource()](./init-resource.md) first, then use `ctx.resource`.
+
+## Use Cases
+
+Use whenever RunJS needs structured data (list, single record, custom API, SQL). Form, table, detail blocks and popups usually have it bound; in JSBlock, JSField, JSItem, JSColumn, etc., call `ctx.initResource(type)` first if you need to load data.
+
+## Type
+
+```ts
+resource: FlowResource | undefined;
+```
+
+- When the context has a bound resource, `ctx.resource` is that instance.
+- In JSBlock etc. it is `undefined` by default; after `ctx.initResource(type)` it is set.
+
+## Common methods
+
+Different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) expose slightly different APIs; common ones:
+
+| Method | Description |
+|--------|-------------|
+| `getData()` | Current data (list or single record) |
+| `setData(value)` | Set local data |
+| `refresh()` | Refetch with current params |
+| `setResourceName(name)` | Set resource name (e.g. `'users'`, `'users.tags'`) |
+| `setFilterByTk(tk)` | Set primary key filter (single get, etc.) |
+| `runAction(actionName, options)` | Call any resource action (e.g. `create`, `update`) |
+| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe (e.g. `refresh`, `saved`) |
+
+**MultiRecordResource**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
+
+## Examples
+
+### List (after initResource)
+
+```js
+ctx.initResource('MultiRecordResource');
+ctx.resource.setResourceName('users');
+await ctx.resource.refresh();
+const rows = ctx.resource.getData();
+```
+
+### Table (pre-bound)
+
+```js
+const rows = ctx.resource?.getSelectedRows?.() || [];
+for (const row of rows) {
+  console.log(row);
+}
+
+await ctx.resource.destroySelectedRows();
+ctx.message.success(ctx.t('Deleted'));
+```
+
+### Single record
+
+```js
+ctx.initResource('SingleRecordResource');
+ctx.resource.setResourceName('users');
+ctx.resource.setFilterByTk(1);
+await ctx.resource.refresh();
+const record = ctx.resource.getData();
+```
+
+### Custom action
+
+```js
+await ctx.resource.runAction('create', { data: { name: 'John' } });
+```
+
+## Relation to ctx.initResource / ctx.makeResource
+
+- **ctx.initResource(type)**: Creates and binds if missing; otherwise returns existing. Ensures `ctx.resource` is set.
+- **ctx.makeResource(type)**: Creates a new instance and returns it; **does not** set `ctx.resource`. Use when you need multiple resources or a temporary one.
+- **ctx.resource**: The bound resource in the current context. Most blocks/popups have it; when not bound it is `undefined` and you must call `ctx.initResource` first.
+
+## Notes
+
+- Prefer null checks: `ctx.resource?.refresh()`, especially in JSBlock and similar contexts.
+- After init, call `setResourceName(name)` then `refresh()` to load data.
+- See the resource type docs for full API.
+
+## Related
+
+- [ctx.initResource()](./init-resource.md): init and bind resource
+- [ctx.makeResource()](./make-resource.md): create resource without binding
+- [MultiRecordResource](../resource/multi-record-resource.md)
+- [SingleRecordResource](../resource/single-record-resource.md)
+- [APIResource](../resource/api-resource.md)
+- [SQLResource](../resource/sql-resource.md)