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

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

@@ -0,0 +1,74 @@
+# ctx.route
+
+Current route match info, corresponding to React Router’s route; used to get the matched route config, params, etc. Use with `ctx.router` and `ctx.location`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField** | Conditional render or display based on `route.pathname` or `route.params` |
+| **Linkage / event flow** | Read route params (e.g. `params.name`) for logic or pass to children |
+| **View navigation** | Compare `ctx.route.pathname` with target path to decide `ctx.router.navigate` |
+
+> Note: `ctx.route` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+
+## Type
+
+```ts
+type RouteOptions = {
+  name?: string;
+  path?: string;
+  params?: Record<string, any>;
+  pathname?: string;
+};
+```
+
+## Common fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pathname` | `string` | Full path of current route; same as `ctx.location.pathname` |
+| `params` | `Record<string, any>` | Dynamic params from route template, e.g. `{ name: 'users' }` |
+| `path` | `string` | Route template, e.g. `/admin/:name` |
+| `name` | `string` | Route unique id; often used for tabs/views |
+
+## Relation to ctx.router, ctx.location
+
+| Use | Recommended |
+|-----|-------------|
+| **Current path** | `ctx.route.pathname` or `ctx.location.pathname`; they match when route is matched |
+| **Route params** | `ctx.route.params`, e.g. `params.name` for current page UID |
+| **Navigate** | `ctx.router.navigate(path)` |
+| **Query params, state** | `ctx.location.search`, `ctx.location.state` |
+
+`ctx.route` is “matched route config”; `ctx.location` is “current URL”; together they describe the current route state.
+
+## Examples
+
+### Read pathname
+
+```ts
+ctx.message.info('Current page: ' + ctx.route.pathname);
+```
+
+### Branch by params
+
+```ts
+if (ctx.route.params?.name === 'users') {
+  // On user management page
+}
+```
+
+### In Flow page
+
+```tsx
+<div>
+  <h1>Current page - {ctx.route.pathname}</h1>
+  <p>Route id: {ctx.route.params?.name}</p>
+</div>
+```
+
+## Related
+
+- [ctx.router](./router.md): navigation; after `ctx.router.navigate()`, `ctx.route` updates
+- [ctx.location](./location.md): current URL (pathname, search, hash, state); use with `ctx.route`

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

@@ -0,0 +1,99 @@
+# ctx.router
+
+Router instance based on React Router; used for programmatic navigation in RunJS. Use with `ctx.route` and `ctx.location`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField** | Button navigates to detail, list, or external link |
+| **Linkage / event flow** | After submit success, `navigate` to list or detail, or pass state to target |
+| **JSAction / event handler** | Navigate on form submit, link click, etc. |
+| **View navigation** | Update URL when switching views |
+
+> Note: `ctx.router` is only available in RunJS when a router context exists (e.g. JSBlock on a page, Flow page, event flow); in pure backend or non-routed contexts (e.g. workflow) it may be empty.
+
+## Type
+
+```typescript
+router: Router
+```
+
+`Router` is from `@remix-run/router`; use `ctx.router.navigate()` for navigation, back, refresh.
+
+## Methods
+
+### ctx.router.navigate()
+
+Navigate to a path, or go back/refresh.
+
+**Signature:**
+
+```typescript
+navigate(to: string | number | null, options?: RouterNavigateOptions): Promise<void>
+```
+
+**Parameters:**
+
+- `to`: Target path (string), relative history position (number, e.g. `-1` for back), or `null` (refresh current page)
+- `options`:
+  - `replace?: boolean`: Replace current history entry (default `false`, i.e. push)
+  - `state?: any`: State passed to the target route. Not in URL; target page reads it via `ctx.location.state`. Use for sensitive or temporary data.
+
+## Examples
+
+### Basic navigation
+
+```ts
+ctx.router.navigate('/admin/users');
+
+ctx.router.navigate(`/admin/users/${recordId}`);
+```
+
+### Replace (no new history entry)
+
+```ts
+ctx.router.navigate('/admin', { replace: true });
+
+ctx.router.navigate(`/admin/users/${newId}`, { replace: true });
+```
+
+### Pass state
+
+```ts
+ctx.router.navigate('/admin/users/123', { 
+  state: { from: 'dashboard', tab: 'profile' } 
+});
+```
+
+### Back and refresh
+
+```ts
+ctx.router.navigate(-1);
+
+ctx.router.navigate(-2);
+
+ctx.router.navigate(null);
+```
+
+## Relation to ctx.route, ctx.location
+
+| Use | Recommended |
+|-----|-------------|
+| **Navigate** | `ctx.router.navigate(path)` |
+| **Current path** | `ctx.route.pathname` or `ctx.location.pathname` |
+| **State from navigation** | `ctx.location.state` |
+| **Route params** | `ctx.route.params` |
+
+`ctx.router` does “navigation”; `ctx.route` and `ctx.location` describe “current route state”.
+
+## Notes
+
+- `navigate(path)` by default pushes a new history entry; user can use browser back.
+- `replace: true` replaces the current entry; use after login redirect, submit-success redirect, etc.
+- **`state`**: Data in `state` is not in the URL; target page reads it via `ctx.location.state`. State is stored in history (back/forward keep it); it is lost on page refresh.
+
+## Related
+
+- [ctx.route](./route.md): current route match (pathname, params)
+- [ctx.location](./location.md): current URL; read `state` here after navigation

package/dist/ai/docs/runjs/context/set-value.md

@@ -0,0 +1,72 @@
+# ctx.setValue()
+
+In JSField, JSItem, and other editable field contexts, sets the current field’s value. Use with `ctx.getValue()` for two-way binding with the form.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField** | Write user selection or computed value in editable custom fields |
+| **JSItem** | Update current cell value in table/sub-table editable items |
+| **JSColumn** | Update row field value when rendering a column |
+
+> Note: `ctx.setValue(v)` is only available in RunJS contexts with form binding; in event flow, linkage, JSBlock, etc. (no field binding) the method may not exist—use optional chaining: `ctx.setValue?.(value)`.
+
+## Type
+
+```ts
+setValue<T = any>(value: T): void;
+```
+
+- **Parameter**: `value` is the value to write; type depends on the field’s form item type.
+
+## Behavior
+
+- `ctx.setValue(v)` updates the current field’s value in the Ant Design Form and triggers linkage and validation.
+- If the form is not yet rendered or the field is not registered, the call may have no effect; use `ctx.getValue()` to confirm.
+
+## Examples
+
+### Two-way binding with getValue
+
+```tsx
+const { Input } = ctx.libs.antd;
+
+const defaultValue = ctx.getValue() ?? '';
+
+ctx.render(
+  <Input
+    defaultValue={defaultValue}
+    onChange={(e) => ctx.setValue(e.target.value)}
+  />
+);
+```
+
+### Set default by condition
+
+```ts
+const status = ctx.getValue();
+if (status == null || status === '') {
+  ctx.setValue?.('draft');
+}
+```
+
+### Write current field when linking others
+
+```ts
+const otherValue = ctx.form?.getFieldValue('type');
+if (otherValue === 'custom') {
+  ctx.setValue?.({ label: 'Custom', value: 'custom' });
+}
+```
+
+## Notes
+
+- In non-editable contexts (e.g. JSField detail mode, JSBlock), `ctx.setValue` may be `undefined`; use `ctx.setValue?.(value)`.
+- For association fields (m2o, o2m, etc.), pass a value that matches the field type (e.g. `{ id, [titleField]: label }`); see field config.
+
+## Related
+
+- [ctx.getValue()](./get-value.md): get current field value; use with setValue for two-way binding
+- [ctx.form](./form.md): Ant Design Form; read/write other fields
+- `js-field:value-change`: container event when value changes from outside; use to update display

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

@@ -0,0 +1,208 @@
+# ctx.sql
+
+`ctx.sql` provides SQL execution and management, often used in RunJS (e.g. JSBlock, event flow) to access the database directly. It supports ad-hoc SQL, running saved SQL templates by ID, parameter binding, template variables (`{{ctx.xxx}}`), and result type control.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Custom reports, complex filtered lists, cross-table aggregation |
+| **Chart block** | Saved SQL templates as chart data source |
+| **Event flow / linkage** | Run predefined SQL and use results in logic |
+| **SQLResource** | With `ctx.initResource('SQLResource')` for paginated lists, etc. |
+
+> Note: `ctx.sql` uses the `flowSql` API to access the database; ensure the current user has execute permission on the target data source.
+
+## Permissions
+
+| Permission | Method | Description |
+|------------|--------|-------------|
+| **Logged-in user** | `runById` | Run by configured SQL template ID |
+| **SQL config permission** | `run`, `save`, `destroy` | Ad-hoc SQL, save/update/delete SQL templates |
+
+Front-end logic for normal users can use `ctx.sql.runById(uid, options)`; for dynamic SQL or template management, the current role must have SQL config permission.
+
+## Type
+
+```ts
+sql: FlowSQLRepository;
+
+interface FlowSQLRepository {
+  run<T = any>(
+    sql: string,
+    options?: {
+      bind?: Record<string, any> | any[];
+      type?: 'selectRows' | 'selectRow' | 'selectVar';
+      dataSourceKey?: string;
+      filter?: Record<string, any>;
+    },
+  ): Promise<T>;
+
+  save(options: { uid: string; sql: string; dataSourceKey?: string }): Promise<void>;
+
+  runById<T = any>(
+    uid: string,
+    options?: {
+      bind?: Record<string, any> | any[];
+      type?: 'selectRows' | 'selectRow' | 'selectVar';
+      dataSourceKey?: string;
+      filter?: Record<string, any>;
+    },
+  ): Promise<T>;
+
+  destroy(uid: string): Promise<void>;
+}
+```
+
+## Common Methods
+
+| Method | Description | Permission |
+|--------|-------------|------------|
+| `ctx.sql.run(sql, options?)` | Run ad-hoc SQL; supports parameter binding and template variables | SQL config |
+| `ctx.sql.save({ uid, sql, dataSourceKey? })` | Save/update SQL template by ID for reuse | SQL config |
+| `ctx.sql.runById(uid, options?)` | Run saved SQL template by ID | Any logged-in user |
+| `ctx.sql.destroy(uid)` | Delete SQL template by ID | SQL config |
+
+- `run`: for debugging SQL; requires config permission.
+- `save`, `destroy`: for managing SQL templates; require config permission.
+- `runById`: available to normal users; only runs saved templates.
+- Call `save` when a SQL template changes.
+
+## Options
+
+### run / runById options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `bind` | `Record<string, any>` \| `any[]` | Bound variables. Object with `:name`, array with `?` |
+| `type` | `'selectRows'` \| `'selectRow'` \| `'selectVar'` | Result type: multiple rows, single row, single value; default `selectRows` |
+| `dataSourceKey` | `string` | Data source key; default is main data source |
+| `filter` | `Record<string, any>` | Extra filter (if supported) |
+
+### save options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `uid` | `string` | Template unique id; use with `runById(uid, ...)` |
+| `sql` | `string` | SQL text; supports `{{ctx.xxx}}` and `:name` / `?` placeholders |
+| `dataSourceKey` | `string` | Optional data source key |
+
+## Template Variables and Parameter Binding
+
+### Template variables `{{ctx.xxx}}`
+
+In SQL you can use `{{ctx.xxx}}` to reference context variables; they are resolved before execution:
+
+```js
+// Reference ctx.user.id
+const user = await ctx.sql.run(
+  'SELECT * FROM users WHERE id = {{ctx.user.id}}',
+  { type: 'selectRow' }
+);
+```
+
+Variable sources are the same as for `ctx.getVar()` (e.g. `ctx.user.*`, `ctx.record.*`, custom `ctx.defineProperty`, etc.).
+
+### Parameter binding
+
+- **Named**: use `:name` in SQL and pass `bind: { name: value }`
+- **Positional**: use `?` in SQL and pass `bind: [value1, value2]`
+
+```js
+// Named
+const users = await ctx.sql.run(
+  'SELECT * FROM users WHERE status = :status AND age > :minAge',
+  { bind: { status: 'active', minAge: 18 }, type: 'selectRows' }
+);
+
+// Positional
+const count = await ctx.sql.run(
+  'SELECT COUNT(*) AS total FROM users WHERE city = ? AND status = ?',
+  { bind: ['Beijing', 'active'], type: 'selectVar' }
+);
+```
+
+## Examples
+
+### Ad-hoc SQL (requires SQL config permission)
+
+```js
+// Multiple rows (default)
+const rows = await ctx.sql.run('SELECT * FROM users LIMIT 10');
+
+// Single row
+const user = await ctx.sql.run(
+  'SELECT * FROM users WHERE id = :id',
+  { bind: { id: 1 }, type: 'selectRow' }
+);
+
+// Single value (e.g. COUNT, SUM)
+const total = await ctx.sql.run(
+  'SELECT COUNT(*) AS total FROM users',
+  { type: 'selectVar' }
+);
+```
+
+### Template variables
+
+```js
+ctx.defineProperty('minId', { get: () => 1 });
+
+const rows = await ctx.sql.run(
+  'SELECT * FROM users WHERE id > {{ctx.minId}}',
+  { type: 'selectRows' }
+);
+```
+
+### Save template and reuse
+
+```js
+// Save (requires SQL config permission)
+await ctx.sql.save({
+  uid: 'active-users-report',
+  sql: 'SELECT * FROM users WHERE status = :status ORDER BY created_at DESC',
+});
+
+// Any logged-in user can run
+const users = await ctx.sql.runById('active-users-report', {
+  bind: { status: 'active' },
+  type: 'selectRows',
+});
+
+// Delete template (requires SQL config permission)
+await ctx.sql.destroy('active-users-report');
+```
+
+### Paginated list (SQLResource)
+
+```js
+// For pagination and filters, use SQLResource
+ctx.initResource('SQLResource');
+ctx.resource.setFilterByTk('saved-sql-uid');  // Saved SQL template ID
+ctx.resource.setBind({ status: 'active' });
+await ctx.resource.refresh();
+const data = ctx.resource.getData();
+const meta = ctx.resource.getMeta();  // page, pageSize, etc.
+```
+
+## Relation to ctx.resource, ctx.request
+
+| Use | Recommended |
+|-----|-------------|
+| **Run SQL** | `ctx.sql.run()` or `ctx.sql.runById()` |
+| **SQL paginated list (block)** | `ctx.initResource('SQLResource')` + `ctx.resource.refresh()` |
+| **Generic HTTP** | `ctx.request()` |
+
+`ctx.sql` wraps the `flowSql` API for SQL; `ctx.request` is for arbitrary API calls.
+
+## Notes
+
+- Use parameter binding (`:name` / `?`) instead of string concatenation to avoid SQL injection.
+- With `type: 'selectVar'` the result is a scalar (e.g. for `COUNT`, `SUM`).
+- Template variables `{{ctx.xxx}}` are resolved before execution; ensure the context defines them.
+
+## Related
+
+- [ctx.resource](./resource.md): data resource; SQLResource uses flowSql internally
+- [ctx.initResource()](./init-resource.md): initialize SQLResource for paginated lists
+- [ctx.request()](./request.md): generic HTTP requests

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

@@ -0,0 +1,79 @@
+# ctx.t()
+
+i18n helper in RunJS for translating copy; uses the current context’s language. Use for buttons, titles, hints, etc.
+
+## Use Cases
+
+Available in all RunJS environments.
+
+## Type
+
+```ts
+t(key: string, options?: Record<string, any>): string
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Translation key or template with placeholders (e.g. `Hello {{name}}`, `{{count}} rows`) |
+| `options` | `object` | Optional. Interpolation (e.g. `{ name: 'John', count: 5 }`) or i18n options (`defaultValue`, `ns`) |
+
+## Returns
+
+- Translated string; if key has no translation and no `defaultValue`, may return the key or the interpolated string.
+
+## Namespace (ns)
+
+RunJS **default namespace is `runjs`**. Without `ns`, `ctx.t(key)` looks up the key in the `runjs` namespace.
+
+```ts
+ctx.t('Submit');  // same as ctx.t('Submit', { ns: 'runjs' })
+
+ctx.t('Submit', { ns: 'myModule' });
+
+ctx.t('Save', { ns: ['runjs', 'common'] });
+```
+
+## Examples
+
+### Simple key
+
+```ts
+ctx.t('Submit');
+ctx.t('No data');
+```
+
+### With interpolation
+
+```ts
+const text = ctx.t('Hello {{name}}', { name: ctx.user?.nickname || 'Guest' });
+ctx.render(`<div>${text}</div>`);
+```
+
+```ts
+ctx.message.success(ctx.t('Processed {{count}} rows', { count: rows.length }));
+```
+
+### Relative time etc.
+
+```ts
+if (minutes < 60) return ctx.t('{{count}} minutes ago', { count: minutes });
+if (hours < 24) return ctx.t('{{count}} hours ago', { count: hours });
+```
+
+### Specify namespace
+
+```ts
+ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
+```
+
+## Notes
+
+- **Localization plugin**: Activate the localization plugin to manage translations. Missing keys can be collected for translation.
+- i18next-style interpolation: use `{{varName}}` in the key and pass the same name in `options`.
+- Language comes from the current context (e.g. `ctx.i18n.language`, user locale).
+
+## Related
+
+- [ctx.i18n](./i18n.md): read or change language

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

@@ -0,0 +1,128 @@
+# ctx.view
+
+The currently active view controller (dialog, drawer, popover, embed, etc.); used to access view-level info and actions. Provided by FlowViewContext; only available inside content opened via `ctx.viewer` or `ctx.openView`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Dialog/drawer content** | In `content`, use `ctx.view.close()` to close, or render `Header`, `Footer` for title and actions |
+| **After form submit** | Call `ctx.view.close(result)` to close and pass result back |
+| **JSBlock / Action** | Check `ctx.view.type` for view type, or read `ctx.view.inputArgs` for open params |
+| **Association select, sub-table** | Read `inputArgs` for `collectionName`, `filterByTk`, `parentId`, etc. for loading data |
+
+> Note: `ctx.view` is only available in RunJS when a view context exists (e.g. inside `ctx.viewer.dialog()` content, dialog form, association selector); in a normal page or backend context it is `undefined`—use optional chaining: `ctx.view?.close?.()`.
+
+## Type
+
+```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>;
+};
+```
+
+## Common properties and methods
+
+| Property/Method | Type | Description |
+|-----------------|------|-------------|
+| `type` | `'drawer' \| 'popover' \| 'dialog' \| 'embed'` | Current view type |
+| `inputArgs` | `Record<string, any>` | Params passed when opening the view |
+| `Header` | `React.FC \| null` | Header component for title and actions |
+| `Footer` | `React.FC \| null` | Footer for buttons, etc. |
+| `close(result?, force?)` | `void` | Close current view; optional `result` passed back to caller |
+| `update(newConfig)` | `void` | Update view config (e.g. width, title) |
+| `navigation` | `ViewNavigation \| undefined` | In-view navigation (tabs, etc.) |
+
+> Currently only `dialog` and `drawer` support `Header` and `Footer`.
+
+## inputArgs (common fields)
+
+Fields in `inputArgs` depend on how the view was opened; common ones:
+
+| Field | Description |
+|-------|-------------|
+| `viewUid` | View UID |
+| `collectionName` | Collection name |
+| `filterByTk` | Primary key filter (single record) |
+| `parentId` | Parent id (associations) |
+| `sourceId` | Source record id |
+| `parentItem` | Parent item data |
+| `scene` | Scene (e.g. `create`, `edit`, `select`) |
+| `onChange` | Callback after select/change |
+| `tabUid` | Current tab UID (in-page) |
+
+Access via `ctx.getVar('ctx.view.inputArgs.xxx')` or `ctx.view.inputArgs.xxx`.
+
+## Examples
+
+### Close current view
+
+```ts
+await ctx.resource.runAction('create', { data: formData });
+ctx.view?.close();
+
+ctx.view?.close({ id: newRecord.id, name: newRecord.name });
+```
+
+### 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}>OK</Button>
+      </Footer>
+    </div>
+  );
+}
+```
+
+### Branch by view type or inputArgs
+
+```ts
+if (ctx.view?.type === 'embed') {
+  ctx.model.setProps('headerStyle', { display: 'none' });
+}
+
+const collectionName = ctx.view?.inputArgs?.collectionName;
+if (collectionName === 'users') {
+  // User selector
+}
+```
+
+## Relation to ctx.viewer, ctx.openView
+
+| Use | Recommended |
+|-----|-------------|
+| **Open new view** | `ctx.viewer.dialog()` / `ctx.viewer.drawer()` or `ctx.openView()` |
+| **Operate current view** | `ctx.view.close()`, `ctx.view.update()` |
+| **Open params** | `ctx.view.inputArgs` |
+
+`ctx.viewer` opens views; `ctx.view` is the current view instance; `ctx.openView` opens configured flow views.
+
+## Notes
+
+- `ctx.view` is only available inside a view; on a normal page it is `undefined`.
+- Use optional chaining: `ctx.view?.close?.()` to avoid errors when no view context.
+- `close(result)` passes `result` to the Promise returned by `ctx.viewer.open()`.
+
+## Related
+
+- [ctx.openView()](./open-view.md): open configured flow view
+- [ctx.modal](./modal.md): lightweight modals (info, confirm, etc.)
+
+> `ctx.viewer` provides `dialog()`, `drawer()`, `popover()`, `embed()`; inside their `content` you can use `ctx.view`.