@nocobase/plugin-flow-engine 2.1.0-alpha.7 → 2.1.0-alpha.9

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

@@ -1,18 +1,18 @@
 # ctx.modal
 
-Shortcut API built on Ant Design Modal for opening modals (info, confirm, etc.) from RunJS. Implemented by `ctx.viewer` / the view system.
+A shortcut API based on Ant Design Modal, used to actively open modal boxes (information prompts, confirmation pop-ups, etc.) in RunJS. It is implemented by `ctx.viewer` / the view system.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / JSField** | Show result, error, or confirmation after user action |
-| **Event flow / action events** | Confirm before submit; use `ctx.exit()` when user cancels |
-| **Linkage** | Show modal when validation fails |
+|------|------|
+| **JSBlock / JSField** | Display operation results, error prompts, or secondary confirmations after user interaction. |
+| **Workflow / Action Events** | Pop-up confirmation before submission; terminate subsequent steps via `ctx.exit()` if the user cancels. |
+| **Linkage Rules** | Pop-up prompts for the user when validation fails. |
 
-> Note: `ctx.modal` is available in RunJS when a view context exists (e.g. JSBlock on a page, event flow); in backend or no-UI contexts it may be absent—use optional chaining: `ctx.modal?.confirm?.()`.
+> Note: `ctx.modal` is available in RunJS environments with a view context (such as JSBlocks within a page, workflows, etc.); it may not exist in the backend or non-UI contexts. It is recommended to use optional chaining (`ctx.modal?.confirm?.()`) when calling it.
 
-## Type
+## Type Definition
 
 ```ts
 modal: {
@@ -20,89 +20,89 @@ modal: {
   success: (config: ModalConfig) => Promise<void>;
   error: (config: ModalConfig) => Promise<void>;
   warning: (config: ModalConfig) => Promise<void>;
-  confirm: (config: ModalConfig) => Promise<boolean>;  // true = OK, false = Cancel
+  confirm: (config: ModalConfig) => Promise<boolean>;  // Returns true if the user clicks OK, false if they cancel
 };
 ```
 
-`ModalConfig` matches Ant Design Modal static method config.
+`ModalConfig` is consistent with the configuration of Ant Design `Modal` static methods.
 
 ## Common Methods
 
-| Method | Returns | Description |
-|--------|--------|-------------|
-| `info(config)` | `Promise<void>` | Info modal |
-| `success(config)` | `Promise<void>` | Success modal |
-| `error(config)` | `Promise<void>` | Error modal |
-| `warning(config)` | `Promise<void>` | Warning modal |
-| `confirm(config)` | `Promise<boolean>` | Confirm; OK → `true`, Cancel → `false` |
+| Method | Return Value | Description |
+|------|--------|------|
+| `info(config)` | `Promise<void>` | Information prompt modal |
+| `success(config)` | `Promise<void>` | Success prompt modal |
+| `error(config)` | `Promise<void>` | Error prompt modal |
+| `warning(config)` | `Promise<void>` | Warning prompt modal |
+| `confirm(config)` | `Promise<boolean>` | Confirmation modal; returns `true` if the user clicks OK, and `false` if they cancel |
 
-## Config
+## Configuration Parameters
 
-Same as Ant Design `Modal`; common fields:
+Consistent with Ant Design `Modal`, common fields include:
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
+|------|------|------|
 | `title` | `ReactNode` | Title |
 | `content` | `ReactNode` | Content |
 | `okText` | `string` | OK button text |
-| `cancelText` | `string` | Cancel button text (`confirm` only) |
-| `onOk` | `() => void \| Promise<void>` | On OK click |
-| `onCancel` | `() => void` | On Cancel click |
+| `cancelText` | `string` | Cancel button text (only for `confirm`) |
+| `onOk` | `() => void \| Promise<void>` | Executed when clicking OK |
+| `onCancel` | `() => void` | Executed when clicking Cancel |
 
-## Relation to ctx.message, ctx.openView
+## Relationship with ctx.message and ctx.openView
 
-| Use | Recommended |
-|-----|-------------|
-| **Short auto-dismiss** | `ctx.message` |
-| **Info/success/error/warning modal** | `ctx.modal.info` / `success` / `error` / `warning` |
-| **Confirm (user choice)** | `ctx.modal.confirm`; use `ctx.exit()` to control flow |
-| **Complex form, list, etc.** | `ctx.openView` for custom view (page/drawer/dialog) |
+| Purpose | Recommended Usage |
+|------|----------|
+| **Lightweight temporary prompt** | `ctx.message`, disappears automatically |
+| **Info/Success/Error/Warning modal** | `ctx.modal.info` / `success` / `error` / `warning` |
+| **Secondary confirmation (requires user choice)** | `ctx.modal.confirm`, used with `ctx.exit()` to control the flow |
+| **Complex interactions like forms or lists** | `ctx.openView` to open a custom view (page/drawer/modal) |
 
 ## Examples
 
-### Simple info
+### Simple Information Modal
 
 ```ts
 ctx.modal.info({
-  title: 'Notice',
+  title: 'Prompt',
   content: 'Operation completed',
 });
 ```
 
-### Confirm and control flow
+### Confirmation Modal and Flow Control
 
 ```ts
 const confirmed = await ctx.modal.confirm({
-  title: 'Confirm delete',
-  content: 'Delete this record?',
-  okText: 'OK',
+  title: 'Confirm Delete',
+  content: 'Are you sure you want to delete this record?',
+  okText: 'Confirm',
   cancelText: 'Cancel',
 });
 if (!confirmed) {
-  ctx.exit();
+  ctx.exit();  // Terminate subsequent steps if the user cancels
   return;
 }
 await ctx.runAction('destroy', { filterByTk: ctx.record?.id });
 ```
 
-### Confirm with onOk
+### Confirmation Modal with onOk
 
 ```ts
 await ctx.modal.confirm({
-  title: 'Confirm submit',
-  content: 'Cannot be changed after submit. Continue?',
+  title: 'Confirm Submission',
+  content: 'Changes cannot be modified after submission. Do you want to continue?',
   async onOk() {
     await ctx.form.submit();
   },
 });
 ```
 
-### Error
+### Error Prompt
 
 ```ts
 try {
   await someOperation();
-  ctx.modal.success({ title: 'Success', content: 'Done' });
+  ctx.modal.success({ title: 'Success', content: 'Operation completed' });
 } catch (e) {
   ctx.modal.error({ title: 'Error', content: e.message });
 }
@@ -110,6 +110,6 @@ try {
 
 ## Related
 
-- [ctx.message](./message.md): short auto-dismiss messages
-- [ctx.exit()](./exit.md): when user cancels confirm, use `if (!confirmed) ctx.exit()`
-- [ctx.openView()](./open-view.md): open custom view for complex flows
+- [ctx.message](./message.md): Lightweight temporary prompt, disappears automatically
+- [ctx.exit()](./exit.md): Commonly used as `if (!confirmed) ctx.exit()` to terminate the flow when a user cancels confirmation
+- [ctx.openView()](./open-view.md): Opens a custom view, suitable for complex interactions

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

@@ -1,58 +1,58 @@
 # ctx.model
 
-The `FlowModel` instance for the current RunJS execution context; the default entry in JSBlock, JSField, JSAction, etc. The concrete type varies: e.g. `BlockModel`, `ActionModel`, `JSEditableFieldModel`.
+The `FlowModel` instance where the current RunJS execution context is located. It serves as the default entry point for scenarios like JSBlock, JSField, and JSAction. The specific type varies depending on the context: it could be a subclass such as `BlockModel`, `ActionModel`, or `JSEditableFieldModel`.
 
-## Use Cases
+## Scenarios
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | `ctx.model` is the block model; access `resource`, `collection`, `setProps`, etc. |
-| **JSField / JSItem / JSColumn** | `ctx.model` is the field model; access `setProps`, `dispatchEvent`, etc. |
-| **Action events / ActionModel** | `ctx.model` is the action model; read/write step params, dispatch events, etc. |
+|------|------|
+| **JSBlock** | `ctx.model` is the current block model. You can access `resource`, `collection`, `setProps`, etc. |
+| **JSField / JSItem / JSColumn** | `ctx.model` is the field model. You can access `setProps`, `dispatchEvent`, etc. |
+| **Action Events / ActionModel** | `ctx.model` is the action model. You can read/write step parameters, dispatch events, etc. |
 
-> Tip: For the **parent block** that hosts the current JS (e.g. form/table block), use `ctx.blockModel`; for **other models** use `ctx.getModel(uid)`.
+> Tip: If you need to access the **parent block carrying the current JS** (e.g., a Form or Table block), use `ctx.blockModel`. To access **other models**, use `ctx.getModel(uid)`.
 
-## Type
+## Type Definition
 
 ```ts
 model: FlowModel;
 ```
 
-`FlowModel` is the base; at runtime it is a subclass (e.g. `BlockModel`, `FormBlockModel`, `TableBlockModel`, `JSEditableFieldModel`, `ActionModel`). Properties and methods depend on the type.
+`FlowModel` is the base class. At runtime, it is an instance of various subclasses (such as `BlockModel`, `FormBlockModel`, `TableBlockModel`, `JSEditableFieldModel`, `ActionModel`, etc.). Available properties and methods depend on the specific type.
 
 ## Common Properties
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `uid` | `string` | Model unique id; use with `ctx.getModel(uid)` or popup binding |
-| `collection` | `Collection` | Collection bound to the model (when block/field is bound to data) |
-| `resource` | `Resource` | Resource instance; refresh, get selected rows, etc. |
-| `props` | `object` | UI/behavior config; update with `setProps` |
-| `subModels` | `Record<string, FlowModel>` | Child models (e.g. form fields, table columns) |
-| `parent` | `FlowModel` | Parent model (if any) |
+|------|------|------|
+| `uid` | `string` | Unique identifier of the model. Can be used for `ctx.getModel(uid)` or popup UID binding. |
+| `collection` | `Collection` | The collection bound to the current model (exists when the block/field is bound to data). |
+| `resource` | `Resource` | Associated resource instance, used for refreshing, getting selected rows, etc. |
+| `props` | `object` | UI/behavior configuration of the model. Can be updated using `setProps`. |
+| `subModels` | `Record<string, FlowModel>` | Collection of child models (e.g., fields within a form, columns within a table). |
+| `parent` | `FlowModel` | Parent model (if any). |
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `setProps(partialProps: any): void` | Update model config and trigger re-render (e.g. `ctx.model.setProps({ loading: true })`) |
-| `dispatchEvent(eventName: string, payload?: any, options?: any): Promise<any[]>` | Dispatch event to the model; runs flows listening for that event. Optional `payload` to handler; `options.debounce` for debounce |
-| `getStepParams?.(flowKey, stepKey)` | Read flow step params (settings panel, custom actions, etc.) |
-| `setStepParams?.(flowKey, stepKey, params)` | Write flow step params |
+|------|------|
+| `setProps(partialProps: any): void` | Updates model configuration and triggers re-rendering (e.g., `ctx.model.setProps({ loading: true })`). |
+| `dispatchEvent(eventName: string, payload?: any, options?: any): Promise<any[]>` | Dispatches an event to the model, triggering workflows configured on that model that listen for the event name. Optional `payload` is passed to the workflow handler; `options.debounce` enables debouncing. |
+| `getStepParams?.(flowKey, stepKey)` | Reads configuration flow step parameters (used in settings panels, custom actions, etc.). |
+| `setStepParams?.(flowKey, stepKey, params)` | Writes configuration flow step parameters. |
 
-## Relation to ctx.blockModel, ctx.getModel
+## Relationship with ctx.blockModel and ctx.getModel
 
-| Need | Recommended |
-|------|-------------|
-| **Model for current execution context** | `ctx.model` |
-| **Parent block of current JS** | `ctx.blockModel`; use for `resource`, `form`, `collection` |
-| **Any model by uid** | `ctx.getModel(uid)` or `ctx.getModel(uid, true)` (cross view stack) |
+| Requirement | Recommended Usage |
+|------|----------|
+| **Model of the current execution context** | `ctx.model` |
+| **Parent block of the current JS** | `ctx.blockModel`. Often used to access `resource`, `form`, or `collection`. |
+| **Get any model by UID** | `ctx.getModel(uid)` or `ctx.getModel(uid, true)` (search across view stacks). |
 
-In JSField, `ctx.model` is the field model and `ctx.blockModel` is the form/table block that hosts it.
+In a JSField, `ctx.model` is the field model, while `ctx.blockModel` is the Form or Table block containing that field.
 
 ## Examples
 
-### Update block/action state
+### Updating Block/Action Status
 
 ```ts
 ctx.model.setProps({ loading: true });
@@ -60,23 +60,26 @@ await doSomething();
 ctx.model.setProps({ loading: false });
 ```
 
-### Dispatch model event
+### Dispatching Model Events
 
 ```ts
+// Dispatch an event to trigger a workflow configured on this model that listens for this event name
 await ctx.model.dispatchEvent('remove');
 
+// When a payload is provided, it is passed to the workflow handler's ctx.inputArgs
 await ctx.model.dispatchEvent('customEvent', { id: 123 });
 ```
 
-### Use uid for popup or cross-model
+### Using UID for Popup Binding or Cross-Model Access
 
 ```ts
 const myUid = ctx.model.uid;
+// In popup configuration, you can pass openerUid: myUid for association
 const other = ctx.getModel('other-block-uid');
 if (other) other.rerender?.();
 ```
 
 ## Related
 
-- [ctx.blockModel](./block-model.md): parent block of current JS
-- [ctx.getModel()](./get-model.md): get another model by uid
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located.
+- [ctx.getModel()](./get-model.md): Get other models by UID.

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

@@ -1,57 +1,57 @@
 # ctx.notification
 
-Global notification API based on Ant Design Notification; shows notifications in the **top-right**. Compared to `ctx.message`, notifications can have title and description and stay longer.
+Based on Ant Design Notification, this global notification API is used to display notification panels in the **top-right corner** of the page. Compared to `ctx.message`, notifications can include a title and description, making them suitable for content that needs to be displayed for a longer period or requires user attention.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock / action events** | Task done, batch result, export done |
-| **Event flow** | System notice after async flow ends |
-| **Longer content** | Full notification with title, description, actions |
+|------|------|
+| **JSBlock / Action Events** | Task completion notifications, batch operation results, export completion, etc. |
+| **FlowEngine** | System-level alerts after asynchronous processes end. |
+| **Content requiring longer display** | Full notifications with titles, descriptions, and action buttons. |
 
-## Type
+## Type Definition
 
 ```ts
 notification: NotificationInstance;
 ```
 
-`NotificationInstance` is the Ant Design notification API.
+`NotificationInstance` is the Ant Design notification interface, providing the following methods.
 
 ## Common Methods
 
 | Method | Description |
-|--------|-------------|
-| `open(config)` | Open with custom config |
-| `success(config)` | Success notification |
-| `info(config)` | Info notification |
-| `warning(config)` | Warning notification |
-| `error(config)` | Error notification |
-| `destroy(key?)` | Close notification by key; no key = close all |
+|------|------|
+| `open(config)` | Opens a notification with custom configuration |
+| `success(config)` | Displays a success notification |
+| `info(config)` | Displays an information notification |
+| `warning(config)` | Displays a warning notification |
+| `error(config)` | Displays an error notification |
+| `destroy(key?)` | Closes the notification with the specified key; if no key is provided, closes all notifications |
 
-**Config** (same as [Ant Design notification](https://ant.design/components/notification)):
+**Configuration Parameters** (Consistent with [Ant Design notification](https://ant.design/components/notification)):
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `message` | `ReactNode` | Title |
-| `description` | `ReactNode` | Description |
-| `duration` | `number` | Auto-close seconds; default 4.5; 0 = no auto-close |
-| `key` | `string` | Unique id for `destroy(key)` |
-| `onClose` | `() => void` | On close |
-| `placement` | `string` | `topLeft` \| `topRight` \| `bottomLeft` \| `bottomRight` |
+|------|------|------|
+| `message` | `ReactNode` | Notification title |
+| `description` | `ReactNode` | Notification description |
+| `duration` | `number` | Auto-close delay (seconds). Default is 4.5 seconds; set to 0 to disable auto-close |
+| `key` | `string` | Unique identifier for the notification, used for `destroy(key)` to close a specific notification |
+| `onClose` | `() => void` | Callback function triggered when the notification is closed |
+| `placement` | `string` | Position: `topLeft` \| `topRight` \| `bottomLeft` \| `bottomRight` |
 
 ## Examples
 
-### Basic
+### Basic Usage
 
 ```ts
 ctx.notification.open({
-  message: 'Success',
-  description: 'Data saved.',
+  message: 'Operation successful',
+  description: 'Data has been saved to the server.',
 });
 ```
 
-### By type
+### Shortcut Calls by Type
 
 ```ts
 ctx.notification.success({
@@ -61,7 +61,7 @@ ctx.notification.success({
 
 ctx.notification.error({
   message: ctx.t('Export failed'),
-  description: ctx.t('Check console for details'),
+  description: ctx.t('Please check the console for details'),
 });
 
 ctx.notification.warning({
@@ -70,36 +70,37 @@ ctx.notification.warning({
 });
 ```
 
-### Custom duration and key
+### Custom Duration and Key
 
 ```ts
 ctx.notification.open({
   key: 'task-123',
   message: ctx.t('Task in progress'),
   description: ctx.t('Please wait...'),
-  duration: 0,
+  duration: 0,  // Do not auto-close
 });
 
+// Manually close after task completion
 ctx.notification.destroy('task-123');
 ```
 
-### Close all
+### Close All Notifications
 
 ```ts
 ctx.notification.destroy();
 ```
 
-## ctx.message vs ctx.notification
+## Difference from ctx.message
 
-| | ctx.message | ctx.notification |
-|---|-------------|-------------------|
-| **Position** | Top center | Top right (configurable) |
-| **Structure** | Single line | Title + description |
-| **Use** | Short, auto-dismiss | Longer, can stay |
-| **Typical** | Success, validation, copy | Task done, system notice |
+| Feature | ctx.message | ctx.notification |
+|------|--------------|------------------|
+| **Position** | Top center of the page | Top right corner (configurable) |
+| **Structure** | Single-line light hint | Includes title + description |
+| **Purpose** | Temporary feedback, disappears automatically | Complete notification, can be displayed for a long time |
+| **Typical Scenarios** | Operation success, validation failure, copy success | Task completion, system messages, longer content requiring user attention |
 
 ## Related
 
-- [ctx.message](./message.md): top-center short messages
-- [ctx.modal](./modal.md): modal confirm
-- [ctx.t()](./t.md): i18n; often used with notification
+- [ctx.message](./message.md) - Top light hint, suitable for quick feedback
+- [ctx.modal](./modal.md) - Modal confirmation, blocking interaction
+- [ctx.t()](./t.md) - Internationalization, often used in conjunction with notifications

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

@@ -1,16 +1,16 @@
 # ctx.off()
 
-Removes a listener registered with `ctx.on(eventName, handler)`. Use with [ctx.on](./on.md) and unsubscribe when appropriate to avoid leaks or duplicate triggers.
+Removes event listeners registered via `ctx.on(eventName, handler)`. It is often used in conjunction with [ctx.on](./on.md) to unsubscribe at the appropriate time, preventing memory leaks or duplicate triggers.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **React useEffect cleanup** | Call in `useEffect` cleanup; remove on unmount |
-| **JSField / JSEditableField** | Unsubscribe from `js-field:value-change` when doing two-way binding |
-| **resource** | Unsubscribe from `ctx.resource.on` (refresh, saved, etc.) |
+|------|------|
+| **React useEffect Cleanup** | Called within the `useEffect` cleanup function to remove listeners when the component unmounts. |
+| **JSField / JSEditableField** | Unsubscribe from `js-field:value-change` during two-way data binding for fields. |
+| **Resource Related** | Unsubscribe from listeners like `refresh` or `saved` registered via `ctx.resource.on`. |
 
-## Type
+## Type Definition
 
 ```ts
 off(eventName: string, handler: (event?: any) => void): void;
@@ -18,7 +18,7 @@ off(eventName: string, handler: (event?: any) => void): void;
 
 ## Examples
 
-### Pair with on in useEffect
+### Paired usage in React useEffect
 
 ```tsx
 React.useEffect(() => {
@@ -28,21 +28,21 @@ React.useEffect(() => {
 }, []);
 ```
 
-### Unsubscribe resource event
+### Unsubscribing from resource events
 
 ```ts
 const handler = () => { /* ... */ };
 ctx.resource?.on('refresh', handler);
-// Later
+// At the appropriate time
 ctx.resource?.off('refresh', handler);
 ```
 
 ## Notes
 
-1. **Same handler reference**: The `handler` passed to `ctx.off` must be the same reference as in `ctx.on`, or it will not be removed.
-2. **Clean up in time**: Call `ctx.off` before unmount or context destroy to avoid leaks.
+1. **Consistent handler reference**: The `handler` passed to `ctx.off` must be the same reference as the one used in `ctx.on`; otherwise, it cannot be correctly removed.
+2. **Timely cleanup**: Call `ctx.off` before the component unmounts or the context is destroyed to avoid memory leaks.
 
-## Related
+## Related Documents
 
-- [ctx.on](./on.md): subscribe to events
-- [ctx.resource](./resource.md): resource and its `on`/`off`
+- [ctx.on](./on.md) - Subscribe to events
+- [ctx.resource](./resource.md) - Resource instance and its `on`/`off` methods

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

@@ -1,16 +1,16 @@
 # ctx.on()
 
-Subscribe to context events in RunJS (e.g. field value change, property change, resource refresh). Events are mapped to custom DOM events on `ctx.element` or the internal event bus on `ctx.resource`.
+Subscribe to context events (such as field value changes, property changes, resource refreshes, etc.) in RunJS. Events are mapped to custom DOM events on `ctx.element` or internal event bus events of `ctx.resource` based on their type.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSField / JSEditableField** | Sync UI when field value changes from outside (form, linkage); two-way binding |
-| **JSBlock / JSItem / JSColumn** | Listen to custom events on the container; react to data/state changes |
-| **resource** | Listen to refresh, save, etc.; run logic after data updates |
+|------|------|
+| **JSField / JSEditableField** | Listen for field value changes from external sources (forms, linkages, etc.) to synchronously update the UI, achieving two-way binding. |
+| **JSBlock / JSItem / JSColumn** | Listen for custom events on the container to respond to data or state changes. |
+| **resource related** | Listen for resource lifecycle events such as refresh or save to execute logic after data updates. |
 
-## Type
+## Type Definition
 
 ```ts
 on(eventName: string, handler: (event?: any) => void): void;
@@ -18,17 +18,17 @@ on(eventName: string, handler: (event?: any) => void): void;
 
 ## Common Events
 
-| Event | Description | Source |
-|-------|-------------|--------|
-| `js-field:value-change` | Field value changed from outside (form linkage, default value) | CustomEvent on `ctx.element`; `ev.detail` = new value |
-| `resource:refresh` | Resource data refreshed | `ctx.resource` event bus |
-| `resource:saved` | Resource save completed | `ctx.resource` event bus |
+| Event Name | Description | Event Source |
+|--------|------|----------|
+| `js-field:value-change` | Field value modified externally (e.g., form linkage, default value update) | CustomEvent on `ctx.element`, where `ev.detail` is the new value |
+| `resource:refresh` | Resource data has been refreshed | `ctx.resource` event bus |
+| `resource:saved` | Resource saving completed | `ctx.resource` event bus |
 
-> Events with `resource:` prefix use `ctx.resource.on`; others typically use DOM events on `ctx.element` when present.
+> Event mapping rules: Events prefixed with `resource:` go through `ctx.resource.on`, while others typically go through DOM events on `ctx.element` (if it exists).
 
 ## Examples
 
-### Two-way binding (React useEffect + cleanup)
+### Field Two-way Binding (React useEffect + Cleanup)
 
 ```tsx
 React.useEffect(() => {
@@ -40,40 +40,41 @@ React.useEffect(() => {
 }, []);
 ```
 
-### Native DOM when ctx.on not available
+### Native DOM Listening (Alternative when ctx.on is unavailable)
 
 ```ts
+// When ctx.on is not provided, you can use ctx.element directly
 const handler = (ev) => {
   if (selectEl) selectEl.value = String(ev?.detail ?? '');
 };
 ctx.element?.addEventListener('js-field:value-change', handler);
-// Cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
+// During cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
 ```
 
-### Update UI after resource refresh
+### Updating UI After Resource Refresh
 
 ```ts
 ctx.resource?.on('refresh', () => {
   const data = ctx.resource?.getData?.();
-  // Update render from data
+  // Update rendering based on data
 });
 ```
 
-## With ctx.off
+## Coordination with ctx.off
 
-- Unsubscribe with [ctx.off](./off.md) when appropriate to avoid leaks or duplicate handlers.
-- In React, usually call `ctx.off` in `useEffect` cleanup.
-- `ctx.off` may not exist; use optional chaining: `ctx.off?.('eventName', handler)`.
+- Listeners registered using `ctx.on` should be removed at the appropriate time via [ctx.off](./off.md) to avoid memory leaks or duplicate triggers.
+- In React, `ctx.off` is typically called within the cleanup function of `useEffect`.
+- `ctx.off` may not exist; it is recommended to use optional chaining: `ctx.off?.('eventName', handler)`.
 
 ## Notes
 
-1. **Pair with off**: Each `ctx.on(eventName, handler)` should have a matching `ctx.off(eventName, handler)` with the same `handler` reference.
-2. **Lifecycle**: Remove listeners before unmount or context destroy to avoid leaks.
-3. **Event support**: Different context types support different events; see component docs.
+1. **Paired Cancellation**: Every `ctx.on(eventName, handler)` should have a corresponding `ctx.off(eventName, handler)`, and the `handler` reference passed must be identical.
+2. **Lifecycle**: Remove listeners before the component unmounts or the context is destroyed to prevent memory leaks.
+3. **Event Availability**: Different context types support different events. Please refer to the specific component documentation for details.
 
-## Related
+## Related Documentation
 
-- [ctx.off](./off.md): remove listener
-- [ctx.element](./element.md): container and DOM events
-- [ctx.resource](./resource.md): resource and its `on`/`off`
-- [ctx.setValue](./set-value.md): sets field value; triggers `js-field:value-change`
+- [ctx.off](./off.md) - Remove event listeners
+- [ctx.element](./element.md) - Rendering container and DOM events
+- [ctx.resource](./resource.md) - Resource instance and its `on`/`off` methods
+- [ctx.setValue](./set-value.md) - Set field value (triggers `js-field:value-change`)