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

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

@@ -1,18 +1,18 @@
 # ctx.modal
 
-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.
+Shortcut API built on Ant Design Modal for opening modals (info, confirm, etc.) from RunJS. Implemented by `ctx.viewer` / the view system.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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. |
+|----------|-------------|
+| **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 |
 
-> 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.
+> 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?.()`.
 
-## Type Definition
+## Type
 
 ```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>;  // Returns true if the user clicks OK, false if they cancel
+  confirm: (config: ModalConfig) => Promise<boolean>;  // true = OK, false = Cancel
 };
 ```
 
-`ModalConfig` is consistent with the configuration of Ant Design `Modal` static methods.
+`ModalConfig` matches Ant Design Modal static method config.
 
 ## Common Methods
 
-| 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 |
+| 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` |
 
-## Configuration Parameters
+## Config
 
-Consistent with Ant Design `Modal`, common fields include:
+Same as Ant Design `Modal`; common fields:
 
 | Parameter | Type | Description |
-|------|------|------|
+|-----------|------|-------------|
 | `title` | `ReactNode` | Title |
 | `content` | `ReactNode` | Content |
 | `okText` | `string` | OK button text |
-| `cancelText` | `string` | Cancel button text (only for `confirm`) |
-| `onOk` | `() => void \| Promise<void>` | Executed when clicking OK |
-| `onCancel` | `() => void` | Executed when clicking Cancel |
+| `cancelText` | `string` | Cancel button text (`confirm` only) |
+| `onOk` | `() => void \| Promise<void>` | On OK click |
+| `onCancel` | `() => void` | On Cancel click |
 
-## Relationship with ctx.message and ctx.openView
+## Relation to ctx.message, ctx.openView
 
-| 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) |
+| 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) |
 
 ## Examples
 
-### Simple Information Modal
+### Simple info
 
 ```ts
 ctx.modal.info({
-  title: 'Prompt',
+  title: 'Notice',
   content: 'Operation completed',
 });
 ```
 
-### Confirmation Modal and Flow Control
+### Confirm and control flow
 
 ```ts
 const confirmed = await ctx.modal.confirm({
-  title: 'Confirm Delete',
-  content: 'Are you sure you want to delete this record?',
-  okText: 'Confirm',
+  title: 'Confirm delete',
+  content: 'Delete this record?',
+  okText: 'OK',
   cancelText: 'Cancel',
 });
 if (!confirmed) {
-  ctx.exit();  // Terminate subsequent steps if the user cancels
+  ctx.exit();
   return;
 }
 await ctx.runAction('destroy', { filterByTk: ctx.record?.id });
 ```
 
-### Confirmation Modal with onOk
+### Confirm with onOk
 
 ```ts
 await ctx.modal.confirm({
-  title: 'Confirm Submission',
-  content: 'Changes cannot be modified after submission. Do you want to continue?',
+  title: 'Confirm submit',
+  content: 'Cannot be changed after submit. Continue?',
   async onOk() {
     await ctx.form.submit();
   },
 });
 ```
 
-### Error Prompt
+### Error
 
 ```ts
 try {
   await someOperation();
-  ctx.modal.success({ title: 'Success', content: 'Operation completed' });
+  ctx.modal.success({ title: 'Success', content: 'Done' });
 } catch (e) {
   ctx.modal.error({ title: 'Error', content: e.message });
 }
@@ -110,6 +110,6 @@ try {
 
 ## Related
 
-- [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
+- [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

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

@@ -1,58 +1,58 @@
 # ctx.model
 
-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`.
+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`.
 
-## Scenarios
+## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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. |
+|----------|-------------|
+| **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. |
 
-> 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)`.
+> 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)`.
 
-## Type Definition
+## Type
 
 ```ts
 model: FlowModel;
 ```
 
-`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.
+`FlowModel` is the base; at runtime it is a subclass (e.g. `BlockModel`, `FormBlockModel`, `TableBlockModel`, `JSEditableFieldModel`, `ActionModel`). Properties and methods depend on the type.
 
 ## Common Properties
 
 | Property | Type | Description |
-|------|------|------|
-| `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). |
+|----------|------|-------------|
+| `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) |
 
 ## Common Methods
 
 | Method | Description |
-|------|------|
-| `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. |
+|--------|-------------|
+| `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 |
 
-## Relationship with ctx.blockModel and ctx.getModel
+## Relation to ctx.blockModel, ctx.getModel
 
-| 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). |
+| 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) |
 
-In a JSField, `ctx.model` is the field model, while `ctx.blockModel` is the Form or Table block containing that field.
+In JSField, `ctx.model` is the field model and `ctx.blockModel` is the form/table block that hosts it.
 
 ## Examples
 
-### Updating Block/Action Status
+### Update block/action state
 
 ```ts
 ctx.model.setProps({ loading: true });
@@ -60,26 +60,23 @@ await doSomething();
 ctx.model.setProps({ loading: false });
 ```
 
-### Dispatching Model Events
+### Dispatch model event
 
 ```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 });
 ```
 
-### Using UID for Popup Binding or Cross-Model Access
+### Use uid for popup or cross-model
 
 ```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): The parent block model where the current JS is located.
-- [ctx.getModel()](./get-model.md): Get other models by UID.
+- [ctx.blockModel](./block-model.md): parent block of current JS
+- [ctx.getModel()](./get-model.md): get another model by uid

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

@@ -1,57 +1,57 @@
 # ctx.notification
 
-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.
+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.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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. |
+|----------|-------------|
+| **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 |
 
-## Type Definition
+## Type
 
 ```ts
 notification: NotificationInstance;
 ```
 
-`NotificationInstance` is the Ant Design notification interface, providing the following methods.
+`NotificationInstance` is the Ant Design notification API.
 
 ## Common Methods
 
 | Method | Description |
-|------|------|
-| `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 |
+|--------|-------------|
+| `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 |
 
-**Configuration Parameters** (Consistent with [Ant Design notification](https://ant.design/components/notification)):
+**Config** (same as [Ant Design notification](https://ant.design/components/notification)):
 
 | Parameter | Type | Description |
-|------|------|------|
-| `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` |
+|-----------|------|-------------|
+| `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` |
 
 ## Examples
 
-### Basic Usage
+### Basic
 
 ```ts
 ctx.notification.open({
-  message: 'Operation successful',
-  description: 'Data has been saved to the server.',
+  message: 'Success',
+  description: 'Data saved.',
 });
 ```
 
-### Shortcut Calls by Type
+### By type
 
 ```ts
 ctx.notification.success({
@@ -61,7 +61,7 @@ ctx.notification.success({
 
 ctx.notification.error({
   message: ctx.t('Export failed'),
-  description: ctx.t('Please check the console for details'),
+  description: ctx.t('Check console for details'),
 });
 
 ctx.notification.warning({
@@ -70,37 +70,36 @@ 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,  // Do not auto-close
+  duration: 0,
 });
 
-// Manually close after task completion
 ctx.notification.destroy('task-123');
 ```
 
-### Close All Notifications
+### Close all
 
 ```ts
 ctx.notification.destroy();
 ```
 
-## Difference from ctx.message
+## ctx.message vs ctx.notification
 
-| 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 |
+| | 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 |
 
 ## Related
 
-- [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
+- [ctx.message](./message.md): top-center short messages
+- [ctx.modal](./modal.md): modal confirm
+- [ctx.t()](./t.md): i18n; often used with notification

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

@@ -1,16 +1,16 @@
 # ctx.off()
 
-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.
+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.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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`. |
+|----------|-------------|
+| **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.) |
 
-## Type Definition
+## Type
 
 ```ts
 off(eventName: string, handler: (event?: any) => void): void;
@@ -18,7 +18,7 @@ off(eventName: string, handler: (event?: any) => void): void;
 
 ## Examples
 
-### Paired usage in React useEffect
+### Pair with on in useEffect
 
 ```tsx
 React.useEffect(() => {
@@ -28,21 +28,21 @@ React.useEffect(() => {
 }, []);
 ```
 
-### Unsubscribing from resource events
+### Unsubscribe resource event
 
 ```ts
 const handler = () => { /* ... */ };
 ctx.resource?.on('refresh', handler);
-// At the appropriate time
+// Later
 ctx.resource?.off('refresh', handler);
 ```
 
 ## Notes
 
-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.
+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.
 
-## Related Documents
+## Related
 
-- [ctx.on](./on.md) - Subscribe to events
-- [ctx.resource](./resource.md) - Resource instance and its `on`/`off` methods
+- [ctx.on](./on.md): subscribe to events
+- [ctx.resource](./resource.md): resource and its `on`/`off`

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

@@ -1,16 +1,16 @@
 # ctx.on()
 
-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.
+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`.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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. |
+|----------|-------------|
+| **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 |
 
-## Type Definition
+## Type
 
 ```ts
 on(eventName: string, handler: (event?: any) => void): void;
@@ -18,17 +18,17 @@ on(eventName: string, handler: (event?: any) => void): void;
 
 ## Common Events
 
-| 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 |
+| 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 mapping rules: Events prefixed with `resource:` go through `ctx.resource.on`, while others typically go through DOM events on `ctx.element` (if it exists).
+> Events with `resource:` prefix use `ctx.resource.on`; others typically use DOM events on `ctx.element` when present.
 
 ## Examples
 
-### Field Two-way Binding (React useEffect + Cleanup)
+### Two-way binding (React useEffect + cleanup)
 
 ```tsx
 React.useEffect(() => {
@@ -40,41 +40,40 @@ React.useEffect(() => {
 }, []);
 ```
 
-### Native DOM Listening (Alternative when ctx.on is unavailable)
+### Native DOM when ctx.on not available
 
 ```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);
-// During cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
+// Cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
 ```
 
-### Updating UI After Resource Refresh
+### Update UI after resource refresh
 
 ```ts
 ctx.resource?.on('refresh', () => {
   const data = ctx.resource?.getData?.();
-  // Update rendering based on data
+  // Update render from data
 });
 ```
 
-## Coordination with ctx.off
+## With ctx.off
 
-- 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)`.
+- 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)`.
 
 ## Notes
 
-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.
+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.
 
-## Related Documentation
+## Related
 
-- [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`)
+- [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`