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

package/dist/ai/docs/runjs/context/exit-all.md

@@ -0,0 +1,96 @@
+# ctx.exitAll()
+
+Terminates the current event flow and all subsequent event flows triggered in the same event dispatch. It is commonly used when all event flows under the current event need to be aborted immediately due to a global error or permission validation failure.
+
+## Use Cases
+
+`ctx.exitAll()` is generally used in JS-executable contexts where it is necessary to **simultaneously abort the current event flow and subsequent event flows triggered by that event**:
+
+| Scenario | Description |
+|------|------|
+| **Event Flow** | Main event flow validation fails (e.g., insufficient permissions), requiring the termination of the main flow and any subsequent flows under the same event that have not yet executed. |
+| **Linkage Rules** | When linkage validation fails, the current linkage and subsequent linkages triggered by the same event must be terminated. |
+| **Action Events** | Pre-action validation fails (e.g., permission check before deletion), requiring the prevention of the main action and subsequent steps. |
+
+> Difference from `ctx.exit()`: `ctx.exit()` only terminates the current event flow; `ctx.exitAll()` terminates the current event flow and any **unexecuted** subsequent event flows in the same event dispatch.
+
+## Type Definition
+
+```ts
+exitAll(): never;
+```
+
+Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which is caught by the FlowEngine to stop the current event flow instance and subsequent event flows under the same event. Once called, the remaining statements in the current JS code will not be executed.
+
+## Comparison with ctx.exit()
+
+| Method | Scope |
+|------|----------|
+| `ctx.exit()` | Only terminates the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows executed **sequentially** under the same event. |
+
+## Execution Mode
+
+- **Sequential Execution**: Event flows under the same event are executed in order. After any event flow calls `ctx.exitAll()`, subsequent event flows will not execute.
+- **Parallel Execution**: Event flows under the same event are executed in parallel. Calling `ctx.exitAll()` in one event flow will not interrupt other concurrent event flows (as they are independent).
+
+## Examples
+
+### Terminate all event flows when permission validation fails
+
+```ts
+// Abort the main event flow and subsequent event flows when permissions are insufficient
+if (!hasPermission(ctx)) {
+  ctx.notification.error({ message: 'No operation permission' });
+  ctx.exitAll();
+}
+```
+
+### Terminate when global pre-validation fails
+
+```ts
+// Example: If associated data is found to be non-deletable before deletion, prevent the main event flow and subsequent actions
+const canDelete = await checkDeletable(ctx.model?.getValue?.());
+if (!canDelete) {
+  ctx.message.error('Cannot delete: associated data exists');
+  ctx.exitAll();
+}
+```
+
+### Choosing between ctx.exit() and ctx.exitAll()
+
+```ts
+// Only the current event flow needs to exit -> Use ctx.exit()
+if (!params.valid) {
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Subsequent event flows are unaffected
+}
+
+// Need to terminate all subsequent event flows under the current event -> Use ctx.exitAll()
+if (!ctx.model?.context?.getPermission?.()) {
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the main event flow and subsequent event flows under the same event are terminated
+}
+```
+
+### Prompt before terminating
+
+```ts
+if (!isValidInput(ctx.form?.getValues?.())) {
+  ctx.message.warning('Please correct the errors in the form first');
+  ctx.exitAll();
+}
+```
+
+## Notes
+
+- After calling `ctx.exitAll()`, subsequent code in the current JS will not execute. It is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- Business code usually does not need to catch `FlowExitAllException`; let the FlowEngine handle it.
+- If you only need to stop the current event flow without affecting subsequent ones, use `ctx.exit()`.
+- In parallel mode, `ctx.exitAll()` only terminates the current event flow and does not interrupt other concurrent event flows.
+
+## Related
+
+- [ctx.exit()](./exit.md): Terminates only the current event flow
+- [ctx.message](./message.md): Message prompts
+- [ctx.modal](./modal.md): Confirmation modal

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

@@ -0,0 +1,104 @@
+# ctx.exit()
+
+Terminates the execution of the current event flow; subsequent steps will not run. It is commonly used when business conditions are not met, the user cancels, or an irrecoverable error occurs.
+
+## Use Cases
+
+`ctx.exit()` is generally used in the following contexts where JS can be executed:
+
+| Scenario | Description |
+|------|------|
+| **Event Flow** | In event flows triggered by form submissions, button clicks, etc., terminates subsequent steps when conditions are not met. |
+| **Linkage Rules** | In field linkages, filter linkages, etc., terminates the current event flow when validation fails or execution needs to be skipped. |
+| **Action Events** | In custom actions (e.g., delete confirmation, pre-save validation), exits when the user cancels or validation fails. |
+
+> Difference from `ctx.exitAll()`: `ctx.exit()` only terminates the current event flow; other event flows under the same event are not affected. `ctx.exitAll()` terminates the current event flow as well as any subsequent event flows under the same event that have not yet been executed.
+
+## Type Definition
+
+```ts
+exit(): never;
+```
+
+Calling `ctx.exit()` throws an internal `FlowExitException`, which is caught by the FlowEngine to stop the current event flow execution. Once called, the remaining statements in the current JS code will not execute.
+
+## Comparison with ctx.exitAll()
+
+| Method | Scope of Effect |
+|------|----------|
+| `ctx.exit()` | Terminates only the current event flow; subsequent event flows are unaffected. |
+| `ctx.exitAll()` | Terminates the current event flow and aborts subsequent event flows under the same event that are set to **execute sequentially**. |
+
+## Examples
+
+### Exit on User Cancellation
+
+```ts
+// In a confirmation modal, terminate the event flow if the user clicks cancel
+if (!confirmed) {
+  ctx.message.info('Operation cancelled');
+  ctx.exit();
+}
+```
+
+### Exit on Parameter Validation Failure
+
+```ts
+// Prompt and terminate when validation fails
+if (!params.value || params.value.length < 3) {
+  ctx.message.error('Invalid parameters, length must be at least 3');
+  ctx.exit();
+}
+```
+
+### Exit When Business Conditions Are Not Met
+
+```ts
+// Terminate if conditions are not met; subsequent steps will not execute
+const record = ctx.model?.getValue?.();
+if (!record || record.status !== 'draft') {
+  ctx.notification.warning({ message: 'Only drafts can be submitted' });
+  ctx.exit();
+}
+```
+
+### Choosing Between ctx.exit() and ctx.exitAll()
+
+```ts
+// Only the current event flow needs to exit → Use ctx.exit()
+if (!params.valid) {
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Other event flows are unaffected
+}
+
+// Need to terminate all subsequent event flows under the current event → Use ctx.exitAll()
+if (!ctx.model?.context?.getPermission?.()) {
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the current event flow and subsequent event flows under the same event are terminated
+}
+```
+
+### Exit Based on User Choice After Modal Confirmation
+
+```ts
+const ok = await ctx.modal?.confirm?.({
+  title: 'Confirm Delete',
+  content: 'This action cannot be undone. Do you want to continue?',
+});
+if (!ok) {
+  ctx.message.info('Cancelled');
+  ctx.exit();
+}
+```
+
+## Notes
+
+- After calling `ctx.exit()`, subsequent code in the current JS will not execute; it is recommended to explain the reason to the user via `ctx.message`, `ctx.notification`, or a modal before calling it.
+- There is usually no need to catch `FlowExitException` in business code; let the FlowEngine handle it.
+- If you need to terminate all subsequent event flows under the current event, use `ctx.exitAll()`.
+
+## Related
+
+- [ctx.exitAll()](./exit-all.md): Terminates the current event flow and subsequent event flows under the same event.
+- [ctx.message](./message.md): Message prompts.
+- [ctx.modal](./modal.md): Confirmation modals.

package/dist/ai/docs/runjs/context/filter-manager.md

@@ -0,0 +1,102 @@
+# ctx.filterManager
+
+The Filter Connection Manager is used to manage the filter associations between filter forms (FilterForm) and data blocks (tables, lists, charts, etc.). It is provided by `BlockGridModel` and is only available within its context (e.g., filter form blocks, data blocks).
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Filter Form Block** | Manages connection configurations between filter items and target blocks; refreshes target data when filters change. |
+| **Data Block (Table/List)** | Acts as a filter target, binding filter conditions via `bindToTarget`. |
+| **Linkage Rules / Custom FilterModel** | Calls `refreshTargetsByFilter` within `doFilter` or `doReset` to trigger target refreshes. |
+| **Connection Field Configuration** | Uses `getConnectFieldsConfig` and `saveConnectFieldsConfig` to maintain field mappings between filters and targets. |
+
+> Note: `ctx.filterManager` is only available in RunJS contexts that have a `BlockGridModel` (e.g., within a page containing a filter form); it is `undefined` in regular JSBlocks or independent pages. It is recommended to use optional chaining before access.
+
+## Type Definitions
+
+```ts
+filterManager: FilterManager;
+
+type FilterConfig = {
+  filterId: string;   // Filter model UID
+  targetId: string;   // Target data block model UID
+  filterPaths?: string[];  // Field paths of the target block
+  operator?: string;  // Filter operator
+};
+
+type ConnectFieldsConfig = {
+  targets: { targetId: string; filterPaths: string[] }[];
+};
+```
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `getFilterConfigs()` | Gets all current filter connection configurations. |
+| `getConnectFieldsConfig(filterId)` | Gets the connection field configuration for a specific filter. |
+| `saveConnectFieldsConfig(filterId, config)` | Saves the connection field configuration for a filter. |
+| `addFilterConfig(config)` | Adds a filter configuration (filterId + targetId + filterPaths). |
+| `removeFilterConfig({ filterId?, targetId?, persist? })` | Removes filter configurations by filterId, targetId, or both. |
+| `bindToTarget(targetId)` | Binds the filter configuration to a target block, triggering its resource to apply the filter. |
+| `unbindFromTarget(targetId)` | Unbinds the filter from the target block. |
+| `refreshTargetsByFilter(filterId | filterId[])` | Refreshes associated target block data based on the filter(s). |
+
+## Core Concepts
+
+- **FilterModel**: A model providing filter conditions (e.g., FilterFormItemModel), which must implement `getFilterValue()` to return the current filter value.
+- **TargetModel**: The data block being filtered; its `resource` must support `addFilterGroup`, `removeFilterGroup`, and `refresh`.
+
+## Examples
+
+### Add Filter Configuration
+
+```ts
+await ctx.filterManager?.addFilterConfig({
+  filterId: 'filter-form-item-uid',
+  targetId: 'table-block-uid',
+  filterPaths: ['status', 'createdAt'],
+  operator: '$eq',
+});
+```
+
+### Refresh Target Blocks
+
+```ts
+// In doFilter / doReset of a filter form
+ctx.filterManager?.refreshTargetsByFilter(ctx.model.uid);
+
+// Refresh targets associated with multiple filters
+ctx.filterManager?.refreshTargetsByFilter(['filter-1', 'filter-2']);
+```
+
+### Connection Field Configuration
+
+```ts
+// Get connection configuration
+const config = ctx.filterManager?.getConnectFieldsConfig(ctx.model.uid);
+
+// Save connection configuration
+await ctx.filterManager?.saveConnectFieldsConfig(ctx.model.uid, {
+  targets: [
+    { targetId: 'table-uid', filterPaths: ['status'] },
+    { targetId: 'chart-uid', filterPaths: ['category'] },
+  ],
+});
+```
+
+### Remove Configuration
+
+```ts
+// Delete all configurations for a specific filter
+await ctx.filterManager?.removeFilterConfig({ filterId: 'filter-uid' });
+
+// Delete all filter configurations for a specific target
+await ctx.filterManager?.removeFilterConfig({ targetId: 'table-uid' });
+```
+
+## Related
+
+- [ctx.resource](./resource.md): The target block's resource must support the filter interface.
+- [ctx.model](./model.md): Used to get the current model's UID for filterId / targetId.

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

@@ -0,0 +1,169 @@
+# ctx.form
+
+The Ant Design Form instance within the current block, used to read/write form fields, trigger validation, and submission. It is equivalent to `ctx.blockModel?.form` and can be used directly in form-related blocks (Form, Edit Form, Sub-form, etc.).
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Read/write other form fields to implement linkage, or perform calculations and validation based on other field values. |
+| **JSItem** | Read/write same-row or other fields within sub-table items to achieve in-table linkage. |
+| **JSColumn** | Read the current row or association field values in a table column for rendering. |
+| **Form Actions / Workflow** | Pre-submission validation, batch updating fields, resetting forms, etc. |
+
+> Note: `ctx.form` is only available in RunJS contexts related to form blocks (Form, Edit Form, Sub-form, etc.). It may not exist in non-form scenarios (such as independent JSBlocks or Table blocks). It is recommended to perform a null check before use: `ctx.form?.getFieldsValue()`.
+
+## Type Definition
+
+```ts
+form: FormInstance<any>;
+```
+
+`FormInstance` is the instance type of Ant Design Form. Common methods are as follows.
+
+## Common Methods
+
+### Reading Form Values
+
+```ts
+// Read values of currently registered fields (defaults to rendered fields only)
+const values = ctx.form.getFieldsValue();
+
+// Read values of all fields (including registered but unrendered fields, e.g., hidden or inside collapsed sections)
+const allValues = ctx.form.getFieldsValue(true);
+
+// Read a single field
+const email = ctx.form.getFieldValue('email');
+
+// Read nested fields (e.g., in a sub-table)
+const amount = ctx.form.getFieldValue(['orders', 0, 'amount']);
+```
+
+### Writing Form Values
+
+```ts
+// Batch update (commonly used for linkage)
+ctx.form.setFieldsValue({
+  status: 'active',
+  updatedAt: new Date(),
+});
+
+// Update a single field
+ctx.form.setFieldValue('remark', 'Updated remark');
+```
+
+### Validation and Submission
+
+```ts
+// Trigger form validation
+await ctx.form.validateFields();
+
+// Trigger form submission
+ctx.form.submit();
+```
+
+### Resetting
+
+```ts
+// Reset all fields
+ctx.form.resetFields();
+
+// Reset only specific fields
+ctx.form.resetFields(['status', 'remark']);
+```
+
+## Relationship with Related Contexts
+
+### ctx.getValue / ctx.setValue
+
+| Scenario | Recommended Usage |
+|------|----------|
+| **Read/Write current field** | `ctx.getValue()` / `ctx.setValue(v)` |
+| **Read/Write other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
+
+Within the current JS field, prioritize using `getValue`/`setValue` to read/write the field itself; use `ctx.form` when you need to access other fields.
+
+### ctx.blockModel
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Read/Write form fields** | `ctx.form` (Equivalent to `ctx.blockModel?.form`, more convenient) |
+| **Access parent block** | `ctx.blockModel` (Contains `collection`, `resource`, etc.) |
+
+### ctx.getVar('ctx.formValues')
+
+Form values must be obtained via `await ctx.getVar('ctx.formValues')` and are not directly exposed as `ctx.formValues`. In a form context, it is preferred to use `ctx.form.getFieldsValue()` to read the latest values in real-time.
+
+## Notes
+
+- `getFieldsValue()` returns only rendered fields by default. To include unrendered fields (e.g., in collapsed sections or hidden by conditional rules), pass `true`: `getFieldsValue(true)`.
+- Paths for nested fields like sub-tables are arrays, e.g., `['orders', 0, 'amount']`. You can use `ctx.namePath` to get the current field's path and construct paths for other columns in the same row.
+- `validateFields()` throws an error object containing `errorFields` and other information. If validation fails before submission, you can use `ctx.exit()` to terminate subsequent steps.
+- In asynchronous scenarios like workflows or linkage rules, `ctx.form` might not be ready yet. It is recommended to use optional chaining or null checks.
+
+## Examples
+
+### Field Linkage: Display different content based on type
+
+```ts
+const type = ctx.form.getFieldValue('type');
+if (type === 'vip') {
+  ctx.form.setFieldsValue({ discount: 0.8 });
+} else {
+  ctx.form.setFieldsValue({ discount: 1 });
+}
+```
+
+### Calculate current field based on other fields
+
+```ts
+const quantity = ctx.form.getFieldValue('quantity') ?? 0;
+const price = ctx.form.getFieldValue('price') ?? 0;
+ctx.setValue(quantity * price);
+```
+
+### Read/Write other columns in the same row within a sub-table
+
+```ts
+// ctx.namePath is the path of the current field in the form, e.g., ['orders', 0, 'amount']
+// Read 'status' in the same row: ['orders', 0, 'status']
+const rowIndex = ctx.namePath?.[1];
+const status = ctx.form.getFieldValue(['orders', rowIndex, 'status']);
+```
+
+### Pre-submission Validation
+
+```ts
+try {
+  await ctx.form.validateFields();
+  // Validation passed, continue with submission logic
+} catch (e) {
+  ctx.message.error('Please check the form fields');
+  ctx.exit();
+}
+```
+
+### Submit after Confirmation
+
+```ts
+const confirmed = await ctx.modal.confirm({
+  title: 'Confirm Submission',
+  content: 'You will not be able to modify this after submission. Continue?',
+  okText: 'Confirm',
+  cancelText: 'Cancel',
+});
+if (confirmed) {
+  await ctx.form.validateFields();
+  ctx.form.submit();
+} else {
+  ctx.exit(); // Terminate if user cancels
+}
+```
+
+## Related
+
+- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): Read and write the current field value.
+- [ctx.blockModel](./block-model.md): Parent block model; `ctx.form` is equivalent to `ctx.blockModel?.form`.
+- [ctx.modal](./modal.md): Confirmation dialogs, often used with `ctx.form.validateFields()` and `ctx.form.submit()`.
+- [ctx.exit()](./exit.md): Terminate the process upon validation failure or user cancellation.
+- `ctx.namePath`: The path (array) of the current field in the form, used to construct names for `getFieldValue` / `setFieldValue` in nested fields.

package/dist/ai/docs/runjs/context/get-model.md

@@ -0,0 +1,85 @@
+# ctx.getModel()
+
+Retrieves a model instance (such as `BlockModel`, `PageModel`, `ActionModel`, etc.) from the current engine or view stack based on the model `uid`. This is used in RunJS to access other models across blocks, pages, or popups.
+
+If you only need the model or block where the current execution context is located, prioritize using `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSAction** | Get models of other blocks based on a known `uid` to read or write their `resource`, `form`, `setProps`, etc. |
+| **RunJS in Popups** | When needing to access a model on the page that opened the popup, pass `searchInPreviousEngines: true`. |
+| **Custom Actions** | Locate forms or sub-models in the configuration panel by `uid` across view stacks to read their configuration or state. |
+
+## Type Definition
+
+```ts
+getModel<T extends FlowModel = FlowModel>(
+  uid: string,
+  searchInPreviousEngines?: boolean
+): T | undefined
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `uid` | `string` | The unique identifier of the target model instance, specified during configuration or creation (e.g., `ctx.model.uid`). |
+| `searchInPreviousEngines` | `boolean` | Optional, defaults to `false`. When `true`, searches from the current engine up to the root in the "view stack," allowing access to models in upper-level engines (e.g., the page that opened a popup). |
+
+## Return Value
+
+- Returns the corresponding `FlowModel` subclass instance (e.g., `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
+- Returns `undefined` if not found.
+
+## Search Scope
+
+- **Default (`searchInPreviousEngines: false`)**: Searches only within the **current engine** by `uid`. In popups or multi-level views, each view has an independent engine; by default, it only searches for models within the current view.
+- **`searchInPreviousEngines: true`**: Searches upwards along the `previousEngine` chain starting from the current engine, returning the first match. This is useful for accessing a model on the page that opened the current popup.
+
+## Examples
+
+### Get another block and refresh
+
+```ts
+const block = ctx.getModel('list-block-uid');
+if (block?.resource) {
+  await block.resource.refresh();
+}
+```
+
+### Access a model on the page from a popup
+
+```ts
+// Access a block on the page that opened the current popup
+const pageBlock = ctx.getModel('page-block-uid', true);
+if (pageBlock) {
+  pageBlock.rerender?.();
+}
+```
+
+### Cross-model read/write and trigger rerender
+
+```ts
+const target = ctx.getModel('other-block-uid');
+if (target) {
+  target.setProps({ loading: true });
+  target.rerender?.();
+}
+```
+
+### Safety check
+
+```ts
+const model = ctx.getModel(someUid);
+if (!model) {
+  ctx.message.warning('Target model does not exist');
+  return;
+}
+```
+
+## Related
+
+- [ctx.model](./model.md): The model where the current execution context is located.
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located; usually accessible without needing `getModel`.

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

@@ -0,0 +1,65 @@
+# ctx.getValue()
+
+In editable field scenarios such as JSField and JSItem, use this to get the latest value of the current field. Combined with `ctx.setValue(v)`, it enables two-way binding with the form.
+
+## Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Read user input or the current form value in editable custom fields. |
+| **JSItem** | Read the current cell value in editable items of tables/sub-tables. |
+| **JSColumn** | Read the field value of the corresponding row during table column rendering. |
+
+> **Note**: `ctx.getValue()` is only available in RunJS contexts with form binding; it does not exist in scenarios without field binding, such as workflows or linkage rules.
+
+## Type Definition
+
+```ts
+getValue<T = any>(): T | undefined;
+```
+
+- **Return Value**: The current field value, whose type is determined by the field's form item type; it may be `undefined` if the field is not registered or not filled.
+
+## Retrieval Order
+
+`ctx.getValue()` retrieves values in the following order:
+
+1. **Form State**: Prioritizes reading from the current state of the Ant Design Form.
+2. **Fallback Value**: If the field is not in the form, it falls back to the field's initial value or props.
+
+> If the form has not finished rendering or the field is not registered, it may return `undefined`.
+
+## Examples
+
+### Render based on current value
+
+```ts
+const current = ctx.getValue();
+if (current == null || current === '') {
+  ctx.render(<span>Please enter content first</span>);
+} else {
+  ctx.render(<span>Current value: {current}</span>);
+}
+```
+
+### Two-way binding with setValue
+
+```tsx
+const { Input } = ctx.libs.antd;
+
+// Read current value as default value
+const defaultValue = ctx.getValue() ?? '';
+
+ctx.render(
+  <Input
+    defaultValue={defaultValue}
+    onChange={(e) => ctx.setValue(e.target.value)}
+  />
+);
+```
+
+## Related
+
+- [ctx.setValue()](./set-value.md) - Set the current field value, used with `getValue` for two-way binding.
+- [ctx.form](./form.md) - Ant Design Form instance, for reading/writing other fields.
+- `js-field:value-change` - Container event triggered when external values change, used to update the display.