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

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 (Forms, Tables, Details, etc.) and pop-up scenarios, the runtime environment pre-binds `ctx.resource`. In scenarios like JSBlock where there is no resource by default, you must first call [ctx.initResource()](./init-resource.md) to initialize it before using it via `ctx.resource`.
+
+## Applicable Scenarios
+
+`ctx.resource` can be used in any RunJS scenario that requires access to structured data (lists, single records, custom APIs, SQL). Forms, Tables, Detail blocks, and pop-ups are typically pre-bound. For JSBlock, JSField, JSItem, JSColumn, etc., if data loading is required, you can call `ctx.initResource(type)` first and then access `ctx.resource`.
+
+## Type Definition
+
+```ts
+resource: FlowResource | undefined;
+```
+
+- In contexts with pre-binding, `ctx.resource` is the corresponding resource instance.
+- In scenarios like JSBlock where there is no resource by default, it is `undefined` until `ctx.initResource(type)` is called.
+
+## Common Methods
+
+Methods exposed by different resource types (MultiRecordResource, SingleRecordResource, APIResource, SQLResource) vary slightly. Below are the universal or commonly used methods:
+
+| Method | Description |
+|------|------|
+| `getData()` | Get current data (list or single record) |
+| `setData(value)` | Set local data |
+| `refresh()` | Initiate a request with current parameters to refresh data |
+| `setResourceName(name)` | Set resource name (e.g., `'users'`, `'users.tags'`) |
+| `setFilterByTk(tk)` | Set primary key filter (for single record `get`, etc.) |
+| `runAction(actionName, options)` | Call any resource action (e.g., `create`, `update`) |
+| `on(event, callback)` / `off(event, callback)` | Subscribe/unsubscribe to events (e.g., `refresh`, `saved`) |
+
+**MultiRecordResource Specific**: `getSelectedRows()`, `destroySelectedRows()`, `setPage()`, `next()`, `previous()`, etc.
+
+## Examples
+
+### List Data (Requires initResource first)
+
+```js
+ctx.initResource('MultiRecordResource');
+ctx.resource.setResourceName('users');
+await ctx.resource.refresh();
+const rows = ctx.resource.getData();
+```
+
+### Table Scenario (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();
+```
+
+### Calling a Custom Action
+
+```js
+await ctx.resource.runAction('create', { data: { name: 'John Doe' } });
+```
+
+## Relationship with ctx.initResource / ctx.makeResource
+
+- **ctx.initResource(type)**: If `ctx.resource` does not exist, it creates and binds one; if it already exists, it returns the existing instance. This ensures `ctx.resource` is available.
+- **ctx.makeResource(type)**: Creates a new resource instance and returns it, but does **not** write it to `ctx.resource`. This is suitable for scenarios requiring multiple independent resources or temporary usage.
+- **ctx.resource**: Accesses the resource already bound to the current context. Most blocks/pop-ups are pre-bound; otherwise, it is `undefined` and requires `ctx.initResource`.
+
+## Notes
+
+- It is recommended to perform a null check before use: `ctx.resource?.refresh()`, especially in scenarios like JSBlock where pre-binding might not exist.
+- After initialization, you must call `setResourceName(name)` to specify the collection before loading data via `refresh()`.
+- For the full API of each Resource type, see the links below.
+
+## Related
+
+- [ctx.initResource()](./init-resource.md) - Initialize and bind a resource to the current context
+- [ctx.makeResource()](./make-resource.md) - Create a new resource instance without binding it to `ctx.resource`
+- [MultiRecordResource](../resource/multi-record-resource.md) - Multiple records/Lists
+- [SingleRecordResource](../resource/single-record-resource.md) - Single record
+- [APIResource](../resource/api-resource.md) - General API resource
+- [SQLResource](../resource/sql-resource.md) - SQL query resource

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

@@ -0,0 +1,76 @@
+# ctx.route
+
+The current route matching information, corresponding to the `route` concept in React Router. It is used to retrieve the current matching route configuration, parameters, and more. It is typically used in conjunction with `ctx.router` and `ctx.location`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSField** | Perform conditional rendering or display the current page identifier based on `route.pathname` or `route.params`. |
+| **Linkage Rules / FlowEngine** | Read route parameters (e.g., `params.name`) for logic branching or to pass them to child components. |
+| **View Navigation** | Internally compare `ctx.route.pathname` with a target path to determine whether to trigger `ctx.router.navigate`. |
+
+> Note: `ctx.route` is only available in RunJS environments that contain a routing context (such as JSBlocks within a page, Flow pages, etc.). It may be null in pure backend or non-routing contexts (such as background workflows).
+
+## Type Definition
+
+```ts
+type RouteOptions = {
+  name?: string;   // Unique route identifier
+  path?: string;   // Route template (e.g., /admin/:name)
+  params?: Record<string, any>;  // Route parameters (e.g., { name: 'users' })
+  pathname?: string;  // Full path of the current route (e.g., /admin/users)
+};
+```
+
+## Common Fields
+
+| Field | Type | Description |
+|------|------|------|
+| `pathname` | `string` | The full path of the current route, consistent with `ctx.location.pathname`. |
+| `params` | `Record<string, any>` | Dynamic parameters parsed from the route template, such as `{ name: 'users' }`. |
+| `path` | `string` | The route template, such as `/admin/:name`. |
+| `name` | `string` | Unique route identifier, commonly used in multi-tab or multi-view scenarios. |
+
+## Relationship with ctx.router and ctx.location
+
+| Purpose | Recommended Usage |
+|------|----------|
+| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname`; both are consistent during matching. |
+| **Read route parameters** | `ctx.route.params`, e.g., `params.name` representing the current page UID. |
+| **Navigation** | `ctx.router.navigate(path)` |
+| **Read query parameters, state** | `ctx.location.search`, `ctx.location.state` |
+
+`ctx.route` focuses on the "matched route configuration," while `ctx.location` focuses on the "current URL location." Together, they provide a complete description of the current routing state.
+
+## Examples
+
+### Reading pathname
+
+```ts
+// Display the current path
+ctx.message.info('Current Page: ' + ctx.route.pathname);
+```
+
+### Branching based on params
+
+```ts
+// params.name is typically the current page UID (e.g., a Flow page identifier)
+if (ctx.route.params?.name === 'users') {
+  // Execute specific logic on the user management page
+}
+```
+
+### Displaying in a Flow page
+
+```tsx
+<div>
+  <h1>Current Page - {ctx.route.pathname}</h1>
+  <p>Route Identifier: {ctx.route.params?.name}</p>
+</div>
+```
+
+## Related
+
+- [ctx.router](./router.md): Route navigation. When `ctx.router.navigate()` changes the path, `ctx.route` will update accordingly.
+- [ctx.location](./location.md): Current URL location (pathname, search, hash, state), used in conjunction with `ctx.route`.

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

@@ -0,0 +1,111 @@
+# ctx.router
+
+A router instance based on React Router, used for programmatic navigation within RunJS. It is typically used in conjunction with `ctx.route` and `ctx.location`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSField** | Navigate to detail pages, list pages, or external links after a button click. |
+| **Linkage Rules / Event Flow** | Execute `navigate` to a list or detail page after successful submission, or pass `state` to the target page. |
+| **JSAction / Event Handling** | Execute route navigation within logic such as form submissions or link clicks. |
+| **View Navigation** | Update the URL via `navigate` during internal view stack switching. |
+
+> Note: `ctx.router` is only available in RunJS environments with a routing context (e.g., JSBlock within a page, Flow pages, event flows, etc.); it may be null in pure backend or non-routing contexts (e.g., Workflows).
+
+## Type Definition
+
+```typescript
+router: Router
+```
+
+`Router` is derived from `@remix-run/router`. In RunJS, navigation operations such as jumping, going back, and refreshing are implemented via `ctx.router.navigate()`.
+
+## Methods
+
+### ctx.router.navigate()
+
+Navigates to a target path, or executes a back/refresh action.
+
+**Signature:**
+
+```typescript
+navigate(to: string | number | null, options?: RouterNavigateOptions): Promise<void>
+```
+
+**Parameters:**
+
+- `to`: Target path (string), relative history position (number, e.g., `-1` to go back), or `null` (to refresh the current page).
+- `options`: Optional configuration.
+  - `replace?: boolean`: Whether to replace the current history entry (default is `false`, which pushes a new entry).
+  - `state?: any`: State to pass to the target route. This data does not appear in the URL and can be accessed via `ctx.location.state` on the target page. It is suitable for sensitive information, temporary data, or information that should not be placed in the URL.
+
+## Examples
+
+### Basic Navigation
+
+```ts
+// Navigate to the user list (pushes a new history entry, allows going back)
+ctx.router.navigate('/admin/users');
+
+// Navigate to a detail page
+ctx.router.navigate(`/admin/users/${recordId}`);
+```
+
+### Replacing History (No new entry)
+
+```ts
+// Redirect to the home page after login; the user won't return to the login page when going back
+ctx.router.navigate('/admin', { replace: true });
+
+// Replace the current page with the detail page after successful form submission
+ctx.router.navigate(`/admin/users/${newId}`, { replace: true });
+```
+
+### Passing State
+
+```ts
+// Carry data during navigation; the target page retrieves it via ctx.location.state
+ctx.router.navigate('/admin/users/123', { 
+  state: { from: 'dashboard', tab: 'profile' } 
+});
+```
+
+### Back and Refresh
+
+```ts
+// Go back one page
+ctx.router.navigate(-1);
+
+// Go back two pages
+ctx.router.navigate(-2);
+
+// Refresh the current page
+ctx.router.navigate(null);
+```
+
+## Relationship with ctx.route and ctx.location
+
+| Purpose | Recommended Usage |
+|------|----------|
+| **Navigation/Jumping** | `ctx.router.navigate(path)` |
+| **Read current path** | `ctx.route.pathname` or `ctx.location.pathname` |
+| **Read state passed during navigation** | `ctx.location.state` |
+| **Read route parameters** | `ctx.route.params` |
+
+`ctx.router` is responsible for "navigation actions," while `ctx.route` and `ctx.location` are responsible for the "current route state."
+
+## Notes
+
+- `navigate(path)` pushes a new history entry by default, allowing users to return via the browser's back button.
+- `replace: true` replaces the current history entry without adding a new one, which is suitable for scenarios like post-login redirection or navigation after successful submission.
+- **Regarding the `state` parameter**:
+  - Data passed via `state` does not appear in the URL, making it suitable for sensitive or temporary data.
+  - It can be accessed via `ctx.location.state` on the target page.
+  - `state` is saved in the browser history and remains accessible during forward/backward navigation.
+  - `state` will be lost after a hard page refresh.
+
+## Related
+
+- [ctx.route](./route.md): Current route match information (pathname, params, etc.).
+- [ctx.location](./location.md): Current URL location (pathname, search, hash, state); `state` is read here after navigation.

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

@@ -0,0 +1,73 @@
+# ctx.setValue()
+
+Sets the value of the current field in editable field scenarios such as JSField and JSItem. Combined with `ctx.getValue()`, it enables two-way binding with the form.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Write user-selected or calculated values into editable custom fields. |
+| **JSItem** | Update the current cell value in editable items of tables/sub-tables. |
+| **JSColumn** | Update the field value of the corresponding row based on logic during table column rendering. |
+
+> **Note**: `ctx.setValue(v)` is only available in RunJS contexts with form binding. It is not available in scenarios without field binding, such as FlowEngine, linkage rules, or JSBlock. It is recommended to use optional chaining before use: `ctx.setValue?.(value)`.
+
+## Type Definition
+
+```ts
+setValue<T = any>(value: T): void;
+```
+
+- **Parameters**: `value` is the field value to be written. The type is determined by the form item type of the field.
+
+## Behavior
+
+- `ctx.setValue(v)` updates the value of the current field in the Ant Design Form and triggers related form linkage and validation logic.
+- If the form has not finished rendering or the field is not registered, the call may be ineffective. It is recommended to use `ctx.getValue()` to confirm the write result.
+
+## 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)}
+  />
+);
+```
+
+### Setting default values based on conditions
+
+```ts
+const status = ctx.getValue();
+if (status == null || status === '') {
+  ctx.setValue?.('draft');
+}
+```
+
+### Writing back to the current field when linked to other fields
+
+```ts
+// Synchronously update the current field when another field changes
+const otherValue = ctx.form?.getFieldValue('type');
+if (otherValue === 'custom') {
+  ctx.setValue?.({ label: 'Custom', value: 'custom' });
+}
+```
+
+## Notes
+
+- In non-editable fields (e.g., JSField in Read-only Mode, JSBlock), `ctx.setValue` may be `undefined`. It is recommended to use `ctx.setValue?.(value)` to avoid errors.
+- When setting values for association fields (M2O, O2M, etc.), you need to pass a structure that matches the field type (e.g., `{ id, [titleField]: label }`), depending on the specific field configuration.
+
+## Related
+
+- [ctx.getValue()](./get-value.md) - Get the current field value, used with setValue for two-way binding.
+- [ctx.form](./form.md) - Ant Design Form instance, used to read or write other fields.
+- `js-field:value-change` - A container event triggered when an external value changes, used to update the display.

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

@@ -0,0 +1,200 @@
+# 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>` | Bound variables. Use `$name` in SQL and pass object `{ name: value }` |
+| `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
+
+- Use `$name` in SQL and pass `bind: { name: value }`
+
+```js
+const users = await ctx.sql.run(
+  'SELECT * FROM users WHERE status = $status AND age > $minAge',
+  { bind: { status: 'active', minAge: 18 }, type: 'selectRows' }
+);
+```
+
+## 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,82 @@
+# ctx.t()
+
+An i18n shortcut function used in RunJS to translate text based on the current context's language settings. It is suitable for internationalizing inline copy such as buttons, titles, and prompts.
+
+## Use Cases
+
+`ctx.t()` can be used in all RunJS execution environments.
+
+## Type Definition
+
+```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 variables (e.g., `{ name: 'John', count: 5 }`), or i18n options (e.g., `defaultValue`, `ns`). |
+
+## Return Value
+
+- Returns the translated string. If no translation exists for the key and no `defaultValue` is provided, it may return the key itself or the interpolated string.
+
+## Namespace (ns)
+
+The **default namespace for the RunJS environment is `runjs`**. When `ns` is not specified, `ctx.t(key)` will look up the key in the `runjs` namespace.
+
+```ts
+// Looks up key from the 'runjs' namespace by default
+ctx.t('Submit'); // Equivalent to ctx.t('Submit', { ns: 'runjs' })
+
+// Looks up key from a specific namespace
+ctx.t('Submit', { ns: 'myModule' });
+
+// Searches multiple namespaces sequentially (first 'runjs', then 'common')
+ctx.t('Save', { ns: ['runjs', 'common'] });
+```
+
+## Examples
+
+### Simple Key
+
+```ts
+ctx.t('Submit');
+ctx.t('No data');
+```
+
+### With Interpolation Variables
+
+```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 }));
+```
+
+### Dynamic Copy (e.g., Relative Time)
+
+```ts
+if (minutes < 60) return ctx.t('{{count}} minutes ago', { count: minutes });
+if (hours < 24) return ctx.t('{{count}} hours ago', { count: hours });
+```
+
+### Specifying a Namespace
+
+```ts
+ctx.t('Hello {{name}}', { name: 'Guest', ns: 'myModule' });
+```
+
+## Notes
+
+- **Localization Plugin**: To translate text, the Localization plugin must be activated. Missing translation keys will be automatically extracted to the localization management list for unified maintenance and translation.
+- Supports i18next-style interpolation: Use `{{variableName}}` in the key and pass the corresponding variable in `options` to replace it.
+- The language is determined by the current context (e.g., `ctx.i18n.language`, user locale).
+
+## Related
+
+- [ctx.i18n](./i18n.md): Read or switch languages