@nocobase/plugin-flow-engine 2.1.0-alpha.6 → 2.1.0-alpha.8

package/dist/ai/docs/runjs/context/open-view.md

@@ -1,17 +1,17 @@
 # ctx.openView()
 
-Opens a configured view (drawer, dialog, embed, etc.) programmatically. Provided by FlowModelContext; used in JSBlock, table cells, event flow, etc. to open ChildPage or PopupAction views.
+Programmatically open a specified view (drawer, dialog, embedded page, etc.). Provided by `FlowModelContext`, it is used to open configured `ChildPage` or `PopupAction` views in scenarios such as `JSBlock`, table cells, and workflows.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Button opens detail/edit dialog; pass current row `filterByTk` |
-| **Table cell** | Button in cell opens row detail dialog |
-| **Event flow / JSAction** | Open next view or dialog after action success |
-| **Association field** | `ctx.runAction('openView', params)` for select/edit dialog |
+|------|------|
+| **JSBlock** | Open a detail/edit dialog after a button click, passing the current row's `filterByTk`. |
+| **Table Cell** | Render a button within a cell that opens a row detail dialog when clicked. |
+| **Workflow / JSAction** | Open the next view or a dialog after a successful operation. |
+| **Association Field** | Open a selection/edit dialog via `ctx.runAction('openView', params)`. |
 
-> Note: `ctx.openView` requires a FlowModel context; if no model exists for the uid, a PopupActionModel is created and persisted.
+> Note: `ctx.openView` is available in a RunJS environment where a `FlowModel` context exists. If the model corresponding to the `uid` does not exist, a `PopupActionModel` will be automatically created and persisted.
 
 ## Signature
 
@@ -23,46 +23,46 @@ openView(uid: string, options?: OpenViewOptions): Promise<void>
 
 ### uid
 
-Unique id of the view model. If missing, it is created and saved. Use a stable uid (e.g. `${ctx.model.uid}-detail`) so the same popup can be reused.
+The unique identifier of the view model. If it does not exist, it will be automatically created and saved. It is recommended to use a stable UID, such as `${ctx.model.uid}-detail`, so that the configuration can be reused when opening the same dialog multiple times.
 
-### options (common fields)
+### Common options Fields
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `mode` | `drawer` / `dialog` / `embed` | How to open: drawer, dialog, embed; default `drawer` |
-| `size` | `small` / `medium` / `large` | Dialog/drawer size; default `medium` |
-| `title` | `string` | View title |
-| `params` | `Record<string, any>` | Arbitrary params passed to the view |
-| `filterByTk` | `any` | Primary key for single-record detail/edit |
-| `sourceId` | `string` | Source record id (associations) |
-| `dataSourceKey` | `string` | Data source |
-| `collectionName` | `string` | Collection name |
-| `associationName` | `string` | Association field name |
-| `navigation` | `boolean` | Use route navigation; forced `false` when passing `defineProperties` / `defineMethods` |
-| `preventClose` | `boolean` | Prevent close |
-| `defineProperties` | `Record<string, PropertyOptions>` | Inject properties into view models |
-| `defineMethods` | `Record<string, Function>` | Inject methods into view models |
+|------|------|------|
+| `mode` | `drawer` / `dialog` / `embed` | Opening method: drawer, dialog, or embedded. Defaults to `drawer`. |
+| `size` | `small` / `medium` / `large` | Size of the dialog or drawer. Defaults to `medium`. |
+| `title` | `string` | View title. |
+| `params` | `Record<string, any>` | Arbitrary parameters passed to the view. |
+| `filterByTk` | `any` | Primary key value, used for single record detail/edit scenarios. |
+| `sourceId` | `string` | Source record ID, used in association scenarios. |
+| `dataSourceKey` | `string` | Data source. |
+| `collectionName` | `string` | Collection name. |
+| `associationName` | `string` | Association field name. |
+| `navigation` | `boolean` | Whether to use route navigation. If `defineProperties` or `defineMethods` are provided, this is forced to `false`. |
+| `preventClose` | `boolean` | Whether to prevent closing. |
+| `defineProperties` | `Record<string, PropertyOptions>` | Dynamically inject properties into the model within the view. |
+| `defineMethods` | `Record<string, Function>` | Dynamically inject methods into the model within the view. |
 
 ## Examples
 
-### Basic: open drawer
+### Basic Usage: Open a Drawer
 
 ```ts
 const popupUid = `${ctx.model.uid}-detail`;
 await ctx.openView(popupUid, {
   mode: 'drawer',
   size: 'medium',
-  title: ctx.t('Detail'),
+  title: ctx.t('Details'),
 });
 ```
 
-### Pass current row context
+### Passing Current Row Context
 
 ```ts
 const primaryKey = ctx.collection?.primaryKey || 'id';
 await ctx.openView(`${ctx.model.uid}-1`, {
   mode: 'dialog',
-  title: ctx.t('Row detail'),
+  title: ctx.t('Row Details'),
   params: {
     filterByTk: ctx.record?.[primaryKey],
     record: ctx.record,
@@ -72,7 +72,7 @@ await ctx.openView(`${ctx.model.uid}-1`, {
 
 ### Open via runAction
 
-When the model has an openView action (e.g. association field, clickable field):
+When a model is configured with an `openView` action (such as association fields or clickable fields), you can call:
 
 ```ts
 await ctx.runAction('openView', {
@@ -83,7 +83,7 @@ await ctx.runAction('openView', {
 });
 ```
 
-### Inject custom context
+### Injecting Custom Context
 
 ```ts
 await ctx.openView(`${ctx.model.uid}-edit`, {
@@ -98,23 +98,23 @@ await ctx.openView(`${ctx.model.uid}-edit`, {
 });
 ```
 
-## Relation to ctx.viewer, ctx.view
+## Relationship with ctx.viewer and ctx.view
 
-| Use | Recommended |
-|-----|-------------|
-| **Open configured flow view** | `ctx.openView(uid, options)` |
+| Purpose | Recommended Usage |
+|------|----------|
+| **Open a configured flow view** | `ctx.openView(uid, options)` |
 | **Open custom content (no flow)** | `ctx.viewer.dialog()` / `ctx.viewer.drawer()` |
-| **Operate current view** | `ctx.view.close()`, `ctx.view.inputArgs` |
+| **Operate on the currently open view** | `ctx.view.close()`, `ctx.view.inputArgs` |
 
-`ctx.openView` opens a FlowPage (ChildPageModel) with a full flow; `ctx.viewer` opens arbitrary React content.
+`ctx.openView` opens a `FlowPage` (`ChildPageModel`), which renders a complete flow page internally; `ctx.viewer` opens arbitrary React content.
 
 ## Notes
 
-- Prefer uids related to `ctx.model.uid` (e.g. `${ctx.model.uid}-xxx`) to avoid conflicts between blocks.
-- When passing `defineProperties` / `defineMethods`, `navigation` is forced to `false` so context is not lost on refresh.
-- Inside a popup, `ctx.view` is the current view and `ctx.view.inputArgs` holds the params passed when opening.
+- It is recommended to associate the `uid` with `ctx.model.uid` (e.g., `${ctx.model.uid}-xxx`) to avoid conflicts between multiple blocks.
+- When `defineProperties` or `defineMethods` are passed, `navigation` is forced to `false` to prevent context loss after a refresh.
+- Inside the dialog, `ctx.view` refers to the current view instance, and `ctx.view.inputArgs` can be used to read the parameters passed during opening.
 
 ## Related
 
-- [ctx.view](./view.md): current view instance
-- [ctx.model](./model.md): current model; use for stable popupUid
+- [ctx.view](./view.md): The currently open view instance.
+- [ctx.model](./model.md): The current model, used to construct a stable `popupUid`.

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

@@ -1,18 +1,18 @@
 # ctx.render()
 
-Renders a React element, HTML string, or DOM node into a container. Without `container`, renders into `ctx.element` and inherits the app’s ConfigProvider, theme, etc.
+Renders React elements, HTML strings, or DOM nodes into a specified container. If `container` is not provided, it defaults to rendering into `ctx.element` and automatically inherits the application's context, such as ConfigProvider and themes.
 
 ## Use Cases
 
 | Scenario | Description |
-|----------|-------------|
-| **JSBlock** | Custom block content (charts, lists, cards, etc.) |
-| **JSField / JSItem / JSColumn** | Custom editable field or table column |
-| **Detail block** | Custom detail field display |
+|------|------|
+| **JSBlock** | Render custom block content (charts, lists, cards, etc.) |
+| **JSField / JSItem / JSColumn** | Render custom displays for editable fields or table columns |
+| **Details Block** | Customize the display format of fields in details pages |
 
-> Note: `ctx.render()` needs a container. If you don’t pass `container` and `ctx.element` is missing (e.g. no-UI logic), an error is thrown.
+> Note: `ctx.render()` requires a rendering container. If `container` is not passed and `ctx.element` does not exist (e.g., in pure logic scenarios without a UI), an error will be thrown.
 
-## Type
+## Type Definition
 
 ```ts
 render(
@@ -22,27 +22,27 @@ render(
 ```
 
 | Parameter | Type | Description |
-|------------|------|-------------|
-| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to render |
-| `container` | `Element` \| `DocumentFragment` (optional) | Target container; default `ctx.element` |
+|------|------|------|
+| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to be rendered |
+| `container` | `Element` \| `DocumentFragment` (Optional) | Target rendering container, defaults to `ctx.element` |
 
-**Returns**:
+**Return Value**:
 
-- For **React element**: `ReactDOMClient.Root` (for later `root.render()` updates).
-- For **HTML string** or **DOM node**: `null`.
+- When rendering a **React element**: Returns `ReactDOMClient.Root`, making it easy to call `root.render()` for subsequent updates.
+- When rendering an **HTML string** or **DOM node**: Returns `null`.
 
-## vnode types
+## vnode Type Description
 
 | Type | Behavior |
-|------|----------|
-| `React.ReactElement` (JSX) | Rendered with React `createRoot`; full React; inherits app context |
-| `string` | Sanitized with DOMPurify and set as container `innerHTML`; existing React root is unmounted first |
-| `Node` (Element, Text, etc.) | Container cleared then `appendChild`; existing React root unmounted first |
-| `DocumentFragment` | Fragment children appended to container; existing React root unmounted first |
+|------|------|
+| `React.ReactElement` (JSX) | Rendered using React's `createRoot`, providing full React capabilities and automatically inheriting the application context. |
+| `string` | Sets the container's `innerHTML` after sanitization with DOMPurify; any existing React root will be unmounted first. |
+| `Node` (Element, Text, etc.) | Appends via `appendChild` after clearing the container; any existing React root will be unmounted first. |
+| `DocumentFragment` | Appends fragment child nodes to the container; any existing React root will be unmounted first. |
 
 ## Examples
 
-### React (JSX)
+### Rendering React Elements (JSX)
 
 ```tsx
 const { Button, Card } = ctx.libs.antd;
@@ -56,23 +56,26 @@ ctx.render(
 );
 ```
 
-### HTML string
+### Rendering HTML Strings
 
 ```ts
 ctx.render('<h1>Hello World</h1>');
 
+// Combining with ctx.t for internationalization
 ctx.render('<div style="padding:16px">' + ctx.t('Content') + '</div>');
 
+// Conditional rendering
 ctx.render(hasData ? `<ul>${items.map(i => `<li>${i}</li>`).join('')}</ul>` : '<span style="color:#999">' + ctx.t('No data') + '</span>');
 ```
 
-### DOM node
+### Rendering DOM Nodes
 
 ```ts
 const div = document.createElement('div');
 div.textContent = 'Hello World';
 ctx.render(div);
 
+// Render an empty container first, then hand it over to a third-party library (e.g., ECharts) for initialization
 const container = document.createElement('div');
 container.style.width = '100%';
 container.style.height = '400px';
@@ -81,29 +84,31 @@ const chart = echarts.init(container);
 chart.setOption({ ... });
 ```
 
-### Custom container
+### Specifying a Custom Container
 
 ```ts
+// Render to a specific DOM element
 const customEl = document.getElementById('my-container');
 ctx.render(<div>Content</div>, customEl);
 ```
 
-### Multiple calls replace content
+### Multiple Calls Will Replace Content
 
 ```ts
+// The second call will replace the existing content in the container
 ctx.render(<div>First</div>);
-ctx.render(<div>Second</div>);  // Only "Second" is shown
+ctx.render(<div>Second</div>);  // Only "Second" will be displayed
 ```
 
 ## Notes
 
-- **Each call replaces**: Content is replaced, not appended.
-- **HTML safety**: HTML is sanitized with DOMPurify; still avoid concatenating untrusted user input.
-- **Don’t touch ctx.element directly**: `ctx.element.innerHTML` is deprecated; use `ctx.render()`.
-- **No container**: When `ctx.element` is `undefined` (e.g. inside a module loaded by `ctx.importAsync`), pass `container` explicitly.
+- **Multiple calls will replace content**: Each `ctx.render()` call replaces the existing content in the container rather than appending to it.
+- **HTML string safety**: Passed HTML is sanitized via DOMPurify to reduce XSS risks, but it is still recommended to avoid concatenating untrusted user input.
+- **Do not manipulate ctx.element directly**: `ctx.element.innerHTML` is deprecated; `ctx.render()` should be used consistently instead.
+- **Pass container when no default exists**: In scenarios where `ctx.element` is `undefined` (e.g., within modules loaded via `ctx.importAsync`), a `container` must be explicitly provided.
 
 ## Related
 
-- [ctx.element](./element.md): default container when `container` is not passed
-- [ctx.libs](./libs.md): React, antd, etc. for JSX
-- [ctx.importAsync()](./import-async.md): load external React/components then use with `ctx.render()`
+- [ctx.element](./element.md) - Default rendering container, used when no container is passed to `ctx.render()`.
+- [ctx.libs](./libs.md) - Built-in libraries like React and Ant Design, used for JSX rendering.
+- [ctx.importAsync()](./import-async.md) - Used in conjunction with `ctx.render()` after loading external React/component libraries on demand.

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

@@ -1,60 +1,60 @@
 # ctx.request()
 
-Sends authenticated HTTP requests from RunJS. Requests use the app’s baseURL, token, locale, role, etc., and the app’s interceptors and error handling.
+Initiate an authenticated HTTP request within RunJS. The request automatically carries the current application's `baseURL`, `Token`, `locale`, `role`, etc., and follows the application's request interception and error handling logic.
 
 ## Use Cases
 
-Use whenever RunJS needs to call a remote HTTP API: JSBlock, JSField, JSItem, JSColumn, event flow, linkage, JSAction, etc.
+Applicable to any scenario in RunJS where a remote HTTP request needs to be initiated, such as JSBlock, JSField, JSItem, JSColumn, Workflow, Linkage, JSAction, etc.
 
-## Type
+## Type Definition
 
 ```typescript
 request(options: RequestOptions): Promise<AxiosResponse<any>>;
 ```
 
-`RequestOptions` extends Axios `AxiosRequestConfig`:
+`RequestOptions` extends Axios's `AxiosRequestConfig`:
 
 ```typescript
 type RequestOptions = AxiosRequestConfig & {
-  skipNotify?: boolean | ((error: any) => boolean);  // Skip global error toast on failure
-  skipAuth?: boolean;                                 // Skip auth redirect (e.g. 401 → login)
+  skipNotify?: boolean | ((error: any) => boolean);  // Whether to skip global error prompts when the request fails
+  skipAuth?: boolean;                                 // Whether to skip authentication redirection (e.g., do not redirect to login page on 401)
 };
 ```
 
-## Common parameters
+## Common Parameters
 
 | Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | string | URL. Supports resource style (e.g. `users:list`, `posts:create`) or full URL |
-| `method` | 'get' \| 'post' \| 'put' \| 'patch' \| 'delete' | HTTP method; default `'get'` |
-| `params` | object | Query params (serialized to URL) |
-| `data` | any | Request body for post/put/patch |
-| `headers` | object | Custom headers |
-| `skipNotify` | boolean \| (error) => boolean | When true or function returns true, no global error message |
-| `skipAuth` | boolean | When true, 401 etc. do not trigger auth redirect (e.g. to login) |
+|------|------|------|
+| `url` | string | Request URL. Supports resource style (e.g., `users:list`, `posts:create`), or a full URL |
+| `method` | 'get' \| 'post' \| 'put' \| 'patch' \| 'delete' | HTTP method, defaults to `'get'` |
+| `params` | object | Query parameters, serialized into the URL |
+| `data` | any | Request body, used for post/put/patch |
+| `headers` | object | Custom request headers |
+| `skipNotify` | boolean \| (error) => boolean | If true or the function returns true, global error prompts will not pop up on failure |
+| `skipAuth` | boolean | If true, 401 errors etc. will not trigger authentication redirection (e.g., redirecting to the login page) |
 
-## Resource-style URL
+## Resource Style URL
 
-NocoBase resource API supports `resource:action` shorthand:
+NocoBase Resource API supports a shorthand `resource:action` format:
 
 | Format | Description | Example |
-|--------|-------------|---------|
-| `collection:action` | Single-table CRUD | `users:list`, `users:get`, `users:create`, `posts:update` |
-| `collection.relation:action` | Association (need `resourceOf` or primary key in URL) | `posts.comments:list` |
+|------|------|------|
+| `collection:action` | Single collection CRUD | `users:list`, `users:get`, `users:create`, `posts:update` |
+| `collection.relation:action` | Associated resources (requires passing the primary key via `resourceOf` or URL) | `posts.comments:list` |
 
-Relative URLs are joined with the app baseURL (usually `/api`). For cross-origin, use a full URL and ensure CORS on the target.
+Relative paths will be concatenated with the application's `baseURL` (usually `/api`); cross-origin requests must use a full URL, and the target service must be configured with CORS.
 
-## Response
+## Response Structure
 
-Returns Axios response. Common usage:
+The return value is an Axios response object. Common fields include:
 
-- `response.data`: response body
-- List APIs often have `data.data` (records) + `data.meta` (pagination)
-- Single/create/update often have `data.data` as one record
+- `response.data`: Response body
+- List interfaces usually return `data.data` (array of records) + `data.meta` (pagination, etc.)
+- Single record/create/update interfaces usually return the record in `data.data`
 
 ## Examples
 
-### List
+### List Query
 
 ```javascript
 const { data } = await ctx.request({
@@ -64,22 +64,22 @@ const { data } = await ctx.request({
 });
 
 const rows = Array.isArray(data?.data) ? data.data : [];
-const meta = data?.meta;
+const meta = data?.meta; // Pagination and other info
 ```
 
-### Create
+### Submit Data
 
 ```javascript
 const res = await ctx.request({
   url: 'users:create',
   method: 'post',
-  data: { nickname: 'John', email: 'john@example.com' },
+  data: { nickname: 'John Doe', email: 'johndoe@example.com' },
 });
 
 const newRecord = res?.data?.data;
 ```
 
-### Filter and sort
+### With Filtering and Sorting
 
 ```javascript
 const res = await ctx.request({
@@ -93,15 +93,16 @@ const res = await ctx.request({
 });
 ```
 
-### Skip error notify
+### Skip Error Notification
 
 ```javascript
 const res = await ctx.request({
   url: 'some:action',
   method: 'get',
-  skipNotify: true,
+  skipNotify: true,  // Do not pop up global message on failure
 });
 
+// Or decide whether to skip based on error type
 const res2 = await ctx.request({
   url: 'some:action',
   method: 'get',
@@ -109,9 +110,9 @@ const res2 = await ctx.request({
 });
 ```
 
-### Cross-origin
+### Cross-Origin Request
 
-For other domains, the target must allow CORS. For its own token, pass in headers:
+When using a full URL to request other domains, the target service must be configured with CORS to allow the current application's origin. If the target interface requires its own token, it can be passed via headers:
 
 ```javascript
 const res = await ctx.request({
@@ -123,12 +124,12 @@ const res2 = await ctx.request({
   url: 'https://api.other.com/items',
   method: 'get',
   headers: {
-    Authorization: 'Bearer <target-token>',
+    Authorization: 'Bearer <target_service_token>',
   },
 });
 ```
 
-### With ctx.render
+### Displaying with ctx.render
 
 ```javascript
 const { data } = await ctx.request({
@@ -140,7 +141,7 @@ const rows = Array.isArray(data?.data) ? data.data : [];
 
 ctx.render([
   '<div style="padding:12px">',
-  '<h4>' + ctx.t('User list') + '</h4>',
+  '<h4>' + ctx.t('User List') + '</h4>',
   '<ul>',
   ...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
   '</ul>',
@@ -150,13 +151,13 @@ ctx.render([
 
 ## Notes
 
-- **Errors**: Failed requests throw; by default a global error message is shown. Use `skipNotify: true` to handle yourself.
-- **Auth**: Same-origin requests automatically send token, locale, role; cross-origin needs CORS and optional token in headers.
-- **ACL**: Requests are subject to ACL; only resources the user can access are available.
+- **Error Handling**: Request failure will throw an exception, and a global error prompt will pop up by default. Use `skipNotify: true` to catch and handle it yourself.
+- **Authentication**: Same-origin requests will automatically carry the current user's Token, locale, and role; cross-origin requests require the target to support CORS and pass the token in headers as needed.
+- **Resource Permissions**: Requests are subject to ACL constraints and can only access resources the current user has permission for.
 
 ## Related
 
-- [ctx.message](./message.md): short feedback after request
-- [ctx.notification](./notification.md): notification after request
-- [ctx.render](./render.md): render result in UI
-- [ctx.makeResource](./make-resource.md): build resource for chained loading (alternative to direct `ctx.request`)
+- [ctx.message](./message.md) - Display lightweight prompts after the request is completed
+- [ctx.notification](./notification.md) - Display notifications after the request is completed
+- [ctx.render](./render.md) - Render request results to the interface
+- [ctx.makeResource](./make-resource.md) - Construct a resource object for chained data loading (alternative to `ctx.request`)

package/dist/ai/docs/runjs/context/require-async.md

@@ -1,12 +1,12 @@
 # ctx.requireAsync()
 
-Loads **UMD/AMD** or global scripts by URL asynchronously; can also load **CSS**. Use for ECharts, Chart.js, FullCalendar (UMD), jQuery plugins, etc. in RunJS; pass a `.css` URL to load and inject styles. If a library provides ESM, prefer [ctx.importAsync()](./import-async.md).
+Asynchronously loads **UMD/AMD** or globally mounted scripts via URL, as well as **CSS**. It is suitable for RunJS scenarios that require UMD/AMD libraries such as ECharts, Chart.js, FullCalendar (UMD version), or jQuery plugins. If a library also provides an ESM version, prioritize using [ctx.importAsync()](./import-async.md).
 
 ## Use Cases
 
-Use whenever RunJS needs to load UMD/AMD/global scripts or CSS: JSBlock, JSField, JSItem, JSColumn, event flow, JSAction, etc. Typical: ECharts, Chart.js, FullCalendar (UMD), dayjs (UMD), jQuery plugins.
+Can be used in any RunJS scenario where UMD/AMD/global scripts or CSS need to be loaded on demand, such as JSBlock, JSField, JSItem, JSColumn, Workflow, JSAction, etc. Typical uses: ECharts, Chart.js, FullCalendar (UMD), dayjs (UMD), jQuery plugins, etc.
 
-## Type
+## Type Definition
 
 ```ts
 requireAsync<T = any>(url: string): Promise<T>;
@@ -16,37 +16,40 @@ requireAsync<T = any>(url: string): Promise<T>;
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `url` | `string` | Script or CSS URL. Supports **shorthand** `<package>@<version>/<path>` (ESM CDN adds `?raw` for raw UMD) or **full URL**. `.css` URLs load and inject styles. |
+| `url` | `string` | The script or CSS address. Supports **shorthand** `<package>@<version>/<file-path>` (appends `?raw` for the original UMD file when resolved via ESM CDN) or a **full URL**. Loads and injects styles if a `.css` file is passed. |
 
-## Returns
+## Return Value
 
-- Loaded library object (first module value from UMD/AMD callback). Many UMD libs attach to `window` (e.g. `window.echarts`); return value may be `undefined`—use the library’s docs for how to access.
-- For `.css` URLs, returns the result of `loadCSS`.
+- The loaded library object (the first module value of the UMD/AMD callback). Many UMD libraries attach themselves to `window` (e.g., `window.echarts`), so the return value might be `undefined`. In such cases, access the global variable as per the library's documentation.
+- Returns the result of `loadCSS` when a `.css` file is passed.
 
-## URL format
+## URL Format Description
 
-- **Shorthand**: e.g. `echarts@5/dist/echarts.min.js`; with default ESM CDN (esm.sh) becomes `https://esm.sh/echarts@5/dist/echarts.min.js?raw`; `?raw` fetches the raw UMD file.
-- **Full URL**: Any CDN URL, e.g. `https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js`.
-- **CSS**: URLs ending in `.css` are loaded and injected.
+- **Shorthand path**: e.g., `echarts@5/dist/echarts.min.js`. Under the default ESM CDN (esm.sh), it requests `https://esm.sh/echarts@5/dist/echarts.min.js?raw`. The `?raw` parameter is used to fetch the original UMD file instead of an ESM wrapper.
+- **Full URL**: Any CDN address can be used directly, such as `https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js`.
+- **CSS**: A URL ending in `.css` will be loaded and injected into the page.
 
-## vs ctx.importAsync()
+## Difference from ctx.importAsync()
 
-- **ctx.requireAsync()**: Loads **UMD/AMD/global** scripts; good for ECharts, Chart.js, FullCalendar (UMD), jQuery plugins; lib often on `window`; return may be the lib or `undefined`.
-- **ctx.importAsync()**: Loads **ESM**; returns module namespace. If a lib has ESM, prefer `ctx.importAsync()` for better module semantics and tree-shaking.
+- **ctx.requireAsync()**: Loads **UMD/AMD/global** scripts. Suitable for ECharts, Chart.js, FullCalendar (UMD), jQuery plugins, etc. Libraries often attach to `window` after loading; the return value may be the library object or `undefined`.
+- **ctx.importAsync()**: Loads **ESM modules** and returns the module namespace. If a library provides ESM, use `ctx.importAsync()` for better module semantics and Tree-shaking.
 
 ## Examples
 
-### Basic
+### Basic Usage
 
 ```javascript
+// Shorthand path (resolved via ESM CDN as ...?raw)
 const echarts = await ctx.requireAsync('echarts@5/dist/echarts.min.js');
 
+// Full URL
 const dayjs = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
 
+// Load CSS and inject into the page
 await ctx.requireAsync('https://cdn.example.com/theme.css');
 ```
 
-### ECharts
+### ECharts Chart
 
 ```javascript
 const container = document.createElement('div');
@@ -59,13 +62,13 @@ if (!echarts) throw new Error('ECharts library not loaded');
 
 const chart = echarts.init(container);
 chart.setOption({
-  title: { text: ctx.t('Sales overview') },
+  title: { text: ctx.t('Sales Overview') },
   series: [{ type: 'pie', data: [{ value: 1, name: ctx.t('A') }] }],
 });
 chart.resize();
 ```
 
-### Chart.js bar
+### Chart.js Bar Chart
 
 ```javascript
 async function renderChart() {
@@ -80,7 +83,7 @@ async function renderChart() {
     type: 'bar',
     data: {
       labels: ['A', 'B', 'C'],
-      datasets: [{ label: ctx.t('Count'), data: [12, 19, 3] }],
+      datasets: [{ label: ctx.t('Quantity'), data: [12, 19, 3] }],
     },
   });
 }
@@ -96,12 +99,12 @@ console.log(dayjs?.default || dayjs);
 
 ## Notes
 
-- **Return shape**: UMD libs vary; return may be the lib or `undefined`; if `undefined`, use the lib’s docs (often `window`).
-- **Network**: Requires CDN access; for intranet set **ESM_CDN_BASE_URL** to your own service.
-- **Choice**: If a lib has both ESM and UMD, prefer `ctx.importAsync()`.
+- **Return value format**: UMD export methods vary; the return value may be the library object or `undefined`. If `undefined`, access it via `window` according to the library's documentation.
+- **Network dependency**: Requires CDN access. In internal network environments, you can point to a self-hosted service via **ESM_CDN_BASE_URL**.
+- **Choosing between importAsync**: If a library provides both ESM and UMD, prioritize `ctx.importAsync()`.
 
 ## Related
 
-- [ctx.importAsync()](./import-async.md): load ESM; good for Vue, dayjs (ESM), etc.
-- [ctx.render()](./render.md): render charts etc. into container
-- [ctx.libs](./libs.md): built-in React, antd, dayjs; no async load
+- [ctx.importAsync()](./import-async.md) - Loads ESM modules, suitable for Vue, dayjs (ESM), etc.
+- [ctx.render()](./render.md) - Renders charts and other components into a container.
+- [ctx.libs](./libs.md) - Built-in React, antd, dayjs, etc., no asynchronous loading required.