@nocobase/plugin-flow-engine 2.1.0-beta.2 → 2.1.0-beta.20

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

@@ -1,57 +1,60 @@
 # ctx.element
 
-The ElementProxy instance for the sandbox DOM container; it is the default render target of `ctx.render()`. Available in JSBlock, JSField, JSItem, JSColumn, and other contexts that have a render container.
+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`.
 
-## Use Cases
+## Applicable Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Block’s DOM container for custom content |
-| **JSField / JSItem / FormJSFieldItem** | Field/item render container (often a `<span>`) |
-| **JSColumn** | Table cell DOM container for custom column content |
+|------|------|
+| **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 render container; in contexts without UI (e.g. pure backend) it may be `undefined`—check before use.
+> 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
+## Type Definition
 
 ```typescript
 element: ElementProxy | undefined;
 
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
 class ElementProxy {
-  __el: HTMLElement;  // Internal native DOM (only for specific cases)
-  innerHTML: string;  // Read/write sanitized with DOMPurify
-  outerHTML: string;
+  __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 passed through (not recommended)
+  // Other HTMLElement methods are passed through (direct use is not recommended)
 }
 ```
 
-## Security
+## Security Requirements
 
-**Recommended: do all rendering via `ctx.render()`.** Do not use `ctx.element`’s DOM APIs directly (e.g. `innerHTML`, `appendChild`, `querySelector`).
+**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 use ctx.render()
+### Why ctx.render() is Recommended
 
-| Benefit | Description |
-|---------|-------------|
-| **Security** | Centralized control, avoids XSS and unsafe DOM use |
-| **React** | Full JSX, components, and lifecycle |
-| **Context** | Inherits app ConfigProvider, theme, etc. |
-| **Conflicts** | Manages React root create/unmount, avoids multiple instances |
+| 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 ctx.element use
+### ❌ 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; use `ctx.render()` instead.
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
 
-### ✅ Recommended: ctx.render()
+### ✅ Recommended: Using ctx.render()
 
 ```ts
+// ✅ Rendering a React component
 const { Button, Card } = ctx.libs.antd;
 ctx.render(
   <Card title={ctx.t('Welcome')}>
@@ -59,40 +62,43 @@ ctx.render(
   </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);
 ```
 
-## Exception: popover anchor
+## Special Case: As a Popover Anchor
 
-When you need the current element as a popover anchor, use `ctx.element?.__el` as the native DOM `target`:
+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>Popover content</div>,
+  content: <div>Popup Content</div>,
 });
 ```
 
-> Use `__el` only for this “current container as anchor” case; do not touch DOM otherwise.
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
 
-## Relation to ctx.render
+## Relationship with ctx.render
 
-- `ctx.render(vnode)` without a `container` argument renders into `ctx.element`.
-- If there is no `ctx.element` and no `container`, an error is thrown.
-- You can pass a container: `ctx.render(vnode, customContainer)`.
+- 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
 
-- Treat `ctx.element` as the internal container for `ctx.render()`; avoid reading or mutating it directly.
-- In contexts without a render container, `ctx.element` is `undefined`; ensure a container exists or pass `container` to `ctx.render()`.
-- ElementProxy’s `innerHTML`/`outerHTML` are sanitized with DOMPurify, but prefer `ctx.render()` for all rendering.
+- `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): render into container
-- [ctx.view](./view.md): current view controller
-- [ctx.modal](./modal.md): modal APIs
+- [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

@@ -1,94 +1,96 @@
 # ctx.exitAll()
 
-Stops the current event flow and all **subsequent** event flows that were triggered in the same event dispatch. Use when a global error or permission check requires stopping every flow for that event.
+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
 
-Use `ctx.exitAll()` in JS-capable contexts when you need to **stop both the current flow and any later flows for the same event**:
+`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 flow fails (e.g. no permission); stop it and any subsequent flows for that event |
-| **Linkage rules** | When linkage validation fails and you want to stop current and subsequent linkage |
-| **Action events** | Pre-action check fails (e.g. delete permission); block the action and later steps |
+|------|------|
+| **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 stops the current flow; `ctx.exitAll()` also stops **subsequent** flows for that event.
+> 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
+## Type Definition
 
 ```ts
 exitAll(): never;
 ```
 
-Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which the engine uses to stop the current flow instance and subsequent flows for the same event. The rest of the current JS does not run.
+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()` | Stops only the current flow; later flows still run |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+|------|----------|
+| `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
+## Execution Mode
 
-- **Sequential**: flows for the same event run one after another; after any flow calls `ctx.exitAll()`, later flows do not run.
-- **Parallel**: flows run in parallel; one flow calling `ctx.exitAll()` does not stop other already-running flows.
+- **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
 
-### Stop all flows on permission failure
+### 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 permission' });
+  ctx.notification.error({ message: 'No operation permission' });
   ctx.exitAll();
 }
 ```
 
-### Stop on global pre-check failure
+### 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: related data exists');
+  ctx.message.error('Cannot delete: associated data exists');
   ctx.exitAll();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow → ctx.exit()
+// Only the current event flow needs to exit -> Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Subsequent event flows are unaffected
 }
 
-// This and all subsequent flows → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event -> Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the main event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Message then exit
+### Prompt before terminating
 
 ```ts
 if (!isValidInput(ctx.form?.getValues?.())) {
-  ctx.message.warning('Please fix form errors first');
+  ctx.message.warning('Please correct the errors in the form first');
   ctx.exitAll();
 }
 ```
 
 ## Notes
 
-- After `ctx.exitAll()`, the rest of the current JS does not run; explain to the user with `ctx.message`, `ctx.notification`, or a dialog before calling.
-- You usually do not need to catch `FlowExitAllException`; the engine handles it.
-- To stop only the current flow, use `ctx.exit()`.
-- In parallel mode, `ctx.exitAll()` only stops the current flow; it does not cancel other concurrent flows.
+- 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): stop only the current flow
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [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

@@ -1,86 +1,89 @@
 # ctx.exit()
 
-Stops the current event flow; later steps in that flow do not run. Often used when business conditions fail, the user cancels, or an unrecoverable error occurs.
+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 used in contexts that execute JS, such as:
+`ctx.exit()` is generally used in the following contexts where JS can be executed:
 
 | Scenario | Description |
-|----------|-------------|
-| **Event flow** | In flows triggered by form submit, button click, etc., stop when conditions are not met |
-| **Linkage rules** | Field or filter linkage; stop when validation fails or execution should be skipped |
-| **Action events** | In custom actions (e.g. delete confirm, pre-save validation), exit when user cancels or validation fails |
+|------|------|
+| **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 stops the **current** event flow; other flows for the same event still run. `ctx.exitAll()` also stops **subsequent** flows for that event.
+> 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
+## Type Definition
 
 ```ts
 exit(): never;
 ```
 
-Calling `ctx.exit()` throws an internal `FlowExitException`, which the event flow engine catches and uses to stop the current flow. Once called, the rest of the current JS does not run.
+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 |
-|--------|--------|
-| `ctx.exit()` | Stops only the current event flow; others unaffected |
-| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+| 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 cancel
+### Exit on User Cancellation
 
 ```ts
+// In a confirmation modal, terminate the event flow if the user clicks cancel
 if (!confirmed) {
-  ctx.message.info('Cancelled');
+  ctx.message.info('Operation cancelled');
   ctx.exit();
 }
 ```
 
-### Exit on validation failure
+### Exit on Parameter Validation Failure
 
 ```ts
+// Prompt and terminate when validation fails
 if (!params.value || params.value.length < 3) {
-  ctx.message.error('Invalid: length must be at least 3');
+  ctx.message.error('Invalid parameters, length must be at least 3');
   ctx.exit();
 }
 ```
 
-### Exit when business condition fails
+### 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 draft can be submitted' });
+  ctx.notification.warning({ message: 'Only drafts can be submitted' });
   ctx.exit();
 }
 ```
 
-### When to use ctx.exit() vs ctx.exitAll()
+### Choosing Between ctx.exit() and ctx.exitAll()
 
 ```ts
-// Only this flow should stop → ctx.exit()
+// Only the current event flow needs to exit → Use ctx.exit()
 if (!params.valid) {
-  ctx.message.error('Invalid params');
-  ctx.exit();
+  ctx.message.error('Invalid parameters');
+  ctx.exit();  // Other event flows are unaffected
 }
 
-// Stop this and all subsequent flows for this event → ctx.exitAll()
+// Need to terminate all subsequent event flows under the current event → Use ctx.exitAll()
 if (!ctx.model?.context?.getPermission?.()) {
-  ctx.notification.warning({ message: 'No permission' });
-  ctx.exitAll();
+  ctx.notification.warning({ message: 'Insufficient permissions' });
+  ctx.exitAll();  // Both the current event flow and subsequent event flows under the same event are terminated
 }
 ```
 
-### Exit after modal confirm
+### Exit Based on User Choice After Modal Confirmation
 
 ```ts
 const ok = await ctx.modal?.confirm?.({
-  title: 'Confirm delete',
-  content: 'Cannot be recovered. Continue?',
+  title: 'Confirm Delete',
+  content: 'This action cannot be undone. Do you want to continue?',
 });
 if (!ok) {
   ctx.message.info('Cancelled');
@@ -90,12 +93,12 @@ if (!ok) {
 
 ## Notes
 
-- After `ctx.exit()`, the rest of the current JS does not run; use `ctx.message`, `ctx.notification`, or a dialog before calling to explain why.
-- You usually do not need to catch `FlowExitException`; the event flow engine handles it.
-- To stop all subsequent flows for the same event, use `ctx.exitAll()`.
+- 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): stop current and subsequent flows for the event
-- [ctx.message](./message.md): message API
-- [ctx.modal](./modal.md): confirm dialog
+- [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

@@ -1,28 +1,28 @@
 # ctx.filterManager
 
-The filter connection manager that links filter forms (FilterForm) to data blocks (tables, lists, charts, etc.). Provided by `BlockGridModel`; only available in that context (e.g. pages with a filter form block).
+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** | Manage connections between filter items and target blocks; refresh targets when filters change |
-| **Data block (table/list)** | Act as filter target; bind filter conditions via `bindToTarget` |
-| **Linkage / custom FilterModel** | In `doFilter`, `doReset`, call `refreshTargetsByFilter` to refresh targets |
-| **Connection field config** | Use `getConnectFieldsConfig`, `saveConnectFieldsConfig` for filter–target field mapping |
+|------|------|
+| **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. pages with a filter form); in a plain JSBlock or standalone page it is `undefined`—check before use.
+> 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
+## Type Definitions
 
 ```ts
 filterManager: FilterManager;
 
 type FilterConfig = {
-  filterId: string;
-  targetId: string;
-  filterPaths?: string[];
-  operator?: string;
+  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 = {
@@ -33,24 +33,24 @@ type ConnectFieldsConfig = {
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `getFilterConfigs()` | All filter connection configs |
-| `getConnectFieldsConfig(filterId)` | Connection field config for a filter |
-| `saveConnectFieldsConfig(filterId, config)` | Save connection field config for a filter |
-| `addFilterConfig(config)` | Add filter config (filterId + targetId + filterPaths) |
-| `removeFilterConfig({ filterId?, targetId?, persist? })` | Remove config by filterId and/or targetId |
-| `bindToTarget(targetId)` | Bind filter to target block; its resource applies the filter |
-| `unbindFromTarget(targetId)` | Unbind filter from target |
-| `refreshTargetsByFilter(filterId or filterId[])` | Refresh target block(s) by filter |
+|------|------|
+| `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). |
 
-## Concepts
+## Core Concepts
 
-- **FilterModel**: Provides filter values (e.g. FilterFormItemModel); must implement `getFilterValue()`.
-- **TargetModel**: Data block being filtered; its `resource` must support `addFilterGroup`, `removeFilterGroup`, `refresh`.
+- **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 config
+### Add Filter Configuration
 
 ```ts
 await ctx.filterManager?.addFilterConfig({
@@ -61,19 +61,23 @@ await ctx.filterManager?.addFilterConfig({
 });
 ```
 
-### Refresh target blocks
+### 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 config
+### 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'] },
@@ -82,15 +86,17 @@ await ctx.filterManager?.saveConnectFieldsConfig(ctx.model.uid, {
 });
 ```
 
-### Remove config
+### 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): target block’s resource must support filter APIs
-- [ctx.model](./model.md): current model uid for filterId / targetId
+- [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.