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

package/dist/ai/docs/runjs/context/data-source.md

@@ -0,0 +1,136 @@
+# ctx.dataSource
+
+The `DataSource` instance bound to the current RunJS execution context, used to access collections, field metadata, and manage collection configurations **within the current data source**. It usually corresponds to the data source selected for the current page or block (e.g., the main database `main`).
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Single Data Source Operations** | Get collection and field metadata when the current data source is known. |
+| **Collection Management** | Get, add, update, or delete collections under the current data source. |
+| **Get Fields by Path** | Use the `collectionName.fieldPath` format to get field definitions (supports association paths). |
+
+> Note: `ctx.dataSource` represents a single data source for the current context. To enumerate or access other data sources, please use [ctx.dataSourceManager](./data-source-manager.md).
+
+## Type Definition
+
+```ts
+dataSource: DataSource;
+
+class DataSource {
+  constructor(options?: Record<string, any>);
+
+  // Read-only properties
+  get flowEngine(): FlowEngine;   // Current FlowEngine instance
+  get displayName(): string;      // Display name (supports i18n)
+  get key(): string;              // Data source key, e.g., 'main'
+  get name(): string;             // Same as key
+
+  // Collection reading
+  getCollections(): Collection[];                      // Get all collections
+  getCollection(name: string): Collection | undefined; // Get collection by name
+  getAssociation(associationName: string): CollectionField | undefined; // Get association field (e.g., users.roles)
+
+  // Collection management
+  addCollection(collection: Collection | CollectionOptions): void;
+  updateCollection(newOptions: CollectionOptions): void;
+  upsertCollection(options: CollectionOptions): Collection | undefined;
+  upsertCollections(collections: CollectionOptions[], options?: { clearFields?: boolean }): void;
+  removeCollection(name: string): void;
+  clearCollections(): void;
+
+  // Field metadata
+  getCollectionField(fieldPath: string): CollectionField | undefined;
+}
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `key` | `string` | Data source key, e.g., `'main'` |
+| `name` | `string` | Same as key |
+| `displayName` | `string` | Display name (supports i18n) |
+| `flowEngine` | `FlowEngine` | Current FlowEngine instance |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `getCollections()` | Gets all collections under the current data source (sorted, with hidden ones filtered). |
+| `getCollection(name)` | Gets a collection by name; `name` can be `collectionName.fieldName` to get the target collection of an association. |
+| `getAssociation(associationName)` | Gets an association field definition by `collectionName.fieldName`. |
+| `getCollectionField(fieldPath)` | Gets a field definition by `collectionName.fieldPath`, supporting association paths like `users.profile.avatar`. |
+
+## Relationship with ctx.dataSourceManager
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to current context** | `ctx.dataSource` |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **Get collection within current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Example
+
+### Get Collections and Fields
+
+```ts
+// Get all collections
+const collections = ctx.dataSource.getCollections();
+
+// Get collection by name
+const users = ctx.dataSource.getCollection('users');
+const primaryKey = users?.filterTargetKey ?? 'id';
+
+// Get field definition by "collectionName.fieldPath" (supports associations)
+const field = ctx.dataSource.getCollectionField('users.profile.avatar');
+const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
+```
+
+### Get Association Fields
+
+```ts
+// Get association field definition by collectionName.fieldName
+const rolesField = ctx.dataSource.getAssociation('users.roles');
+if (rolesField?.isAssociationField()) {
+  const targetCol = rolesField.targetCollection;
+  // Process based on target collection structure
+}
+```
+
+### Iterate Through Collections for Dynamic Processing
+
+```ts
+const collections = ctx.dataSource.getCollections();
+for (const col of collections) {
+  const fields = col.getFields();
+  const requiredFields = fields.filter((f) => f.options?.required);
+  // ...
+}
+```
+
+### Perform Validation or Dynamic UI Based on Field Metadata
+
+```ts
+const field = ctx.dataSource.getCollectionField('users.status');
+if (field) {
+  const options = field.enum ?? [];
+  const operators = field.getFilterOperators();
+  // Perform UI logic or validation based on interface, enum, validation, etc.
+}
+```
+
+## Notes
+
+- The path format for `getCollectionField(fieldPath)` is `collectionName.fieldPath`, where the first segment is the collection name and the subsequent segments are the field path (supports associations, e.g., `user.name`).
+- `getCollection(name)` supports the `collectionName.fieldName` format, returning the target collection of the association field.
+- In the RunJS context, `ctx.dataSource` is usually determined by the data source of the current block or page. If no data source is bound to the context, it may be `undefined`; it is recommended to perform a null check before use.
+
+## Related
+
+- [ctx.dataSourceManager](./data-source-manager.md): Data source manager, manages all data sources.
+- [ctx.collection](./collection.md): The collection associated with the current context.
+- [ctx.collectionField](./collection-field.md): The collection field definition for the current field.

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

@@ -0,0 +1,104 @@
+# ctx.element
+
+An `ElementProxy` instance pointing to the sandbox DOM container, serving as the default rendering target for `ctx.render()`. It is available in scenarios where a rendering container exists, such as `JSBlock`, `JSField`, `JSItem`, and `JSColumn`.
+
+## Applicable Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | The DOM container for the block, used to render custom block content. |
+| **JSField / JSItem / FormJSFieldItem** | The rendering container for a field or form item (usually a `<span>`). |
+| **JSColumn** | The DOM container for a table cell, used to render custom column content. |
+
+> Note: `ctx.element` is only available in RunJS contexts that have a rendering container. In contexts without a UI (such as pure backend logic), it may be `undefined`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```typescript
+element: ElementProxy | undefined;
+
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
+class ElementProxy {
+  __el: HTMLElement;  // The internal raw DOM element (accessible only in specific scenarios)
+  innerHTML: string;  // Sanitized via DOMPurify during read/write
+  outerHTML: string; // Same as above
+  appendChild(child: HTMLElement | string): void;
+  // Other HTMLElement methods are passed through (direct use is not recommended)
+}
+```
+
+## Security Requirements
+
+**Recommended: All rendering should be performed via `ctx.render()`.** Avoid using the DOM APIs of `ctx.element` directly (e.g., `innerHTML`, `appendChild`, `querySelector`, etc.).
+
+### Why ctx.render() is Recommended
+
+| Advantage | Description |
+|------|------|
+| **Security** | Centralized security control to prevent XSS and improper DOM operations. |
+| **React Support** | Full support for JSX, React components, and lifecycles. |
+| **Context Inheritance** | Automatically inherits the application's `ConfigProvider`, themes, etc. |
+| **Conflict Handling** | Automatically manages React root creation/unmounting to avoid multi-instance conflicts. |
+
+### ❌ Not Recommended: Direct Manipulation of ctx.element
+
+```ts
+// ❌ Not recommended: Using ctx.element APIs directly
+ctx.element.innerHTML = '<div>Content</div>';
+ctx.element.appendChild(node);
+ctx.element.querySelector('.class');
+```
+
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
+
+### ✅ Recommended: Using ctx.render()
+
+```ts
+// ✅ Rendering a React component
+const { Button, Card } = ctx.libs.antd;
+ctx.render(
+  <Card title={ctx.t('Welcome')}>
+    <Button type="primary">Click</Button>
+  </Card>
+);
+
+// ✅ Rendering an HTML string
+ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
+
+// ✅ Rendering a DOM node
+const div = document.createElement('div');
+div.textContent = ctx.t('Hello');
+ctx.render(div);
+```
+
+## Special Case: As a Popover Anchor
+
+When you need to open a Popover using the current element as an anchor, you can access `ctx.element?.__el` to get the raw DOM as the `target`:
+
+```ts
+// ctx.viewer.popover requires a raw DOM as the target
+await ctx.viewer.popover({
+  target: ctx.element?.__el,
+  content: <div>Popup Content</div>,
+});
+```
+
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
+
+## Relationship with ctx.render
+
+- If `ctx.render(vnode)` is called without a `container` argument, it renders into the `ctx.element` container by default.
+- If both `ctx.element` is missing and no `container` is provided, an error will be thrown.
+- You can explicitly specify a container: `ctx.render(vnode, customContainer)`.
+
+## Notes
+
+- `ctx.element` is intended for internal use by `ctx.render()`. Directly accessing or modifying its properties/methods is not recommended.
+- In contexts without a rendering container, `ctx.element` will be `undefined`. Ensure the container is available or pass a `container` manually before calling `ctx.render()`.
+- Although `innerHTML`/`outerHTML` in `ElementProxy` are sanitized via DOMPurify, it is still recommended to use `ctx.render()` for unified rendering management.
+
+## Related
+
+- [ctx.render](./render.md): Rendering content into a container
+- [ctx.view](./view.md): Current view controller
+- [ctx.modal](./modal.md): Shortcut API for modals

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.