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

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

@@ -1,17 +1,17 @@
 # ctx.openView()
 
-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.
+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.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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)`. |
+|----------|-------------|
+| **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 |
 
-> 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.
+> Note: `ctx.openView` requires a FlowModel context; if no model exists for the uid, a PopupActionModel is created and persisted.
 
 ## Signature
 
@@ -23,46 +23,46 @@ openView(uid: string, options?: OpenViewOptions): Promise<void>
 
 ### uid
 
-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.
+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.
 
-### Common options Fields
+### options (common fields)
 
 | Field | Type | Description |
-|------|------|------|
-| `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. |
+|-------|------|-------------|
+| `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 |
 
 ## Examples
 
-### Basic Usage: Open a Drawer
+### Basic: open drawer
 
 ```ts
 const popupUid = `${ctx.model.uid}-detail`;
 await ctx.openView(popupUid, {
   mode: 'drawer',
   size: 'medium',
-  title: ctx.t('Details'),
+  title: ctx.t('Detail'),
 });
 ```
 
-### Passing Current Row Context
+### Pass current row context
 
 ```ts
 const primaryKey = ctx.collection?.primaryKey || 'id';
 await ctx.openView(`${ctx.model.uid}-1`, {
   mode: 'dialog',
-  title: ctx.t('Row Details'),
+  title: ctx.t('Row detail'),
   params: {
     filterByTk: ctx.record?.[primaryKey],
     record: ctx.record,
@@ -72,7 +72,7 @@ await ctx.openView(`${ctx.model.uid}-1`, {
 
 ### Open via runAction
 
-When a model is configured with an `openView` action (such as association fields or clickable fields), you can call:
+When the model has an openView action (e.g. association field, clickable field):
 
 ```ts
 await ctx.runAction('openView', {
@@ -83,7 +83,7 @@ await ctx.runAction('openView', {
 });
 ```
 
-### Injecting Custom Context
+### Inject custom context
 
 ```ts
 await ctx.openView(`${ctx.model.uid}-edit`, {
@@ -98,23 +98,23 @@ await ctx.openView(`${ctx.model.uid}-edit`, {
 });
 ```
 
-## Relationship with ctx.viewer and ctx.view
+## Relation to ctx.viewer, ctx.view
 
-| Purpose | Recommended Usage |
-|------|----------|
-| **Open a configured flow view** | `ctx.openView(uid, options)` |
+| Use | Recommended |
+|-----|-------------|
+| **Open configured flow view** | `ctx.openView(uid, options)` |
 | **Open custom content (no flow)** | `ctx.viewer.dialog()` / `ctx.viewer.drawer()` |
-| **Operate on the currently open view** | `ctx.view.close()`, `ctx.view.inputArgs` |
+| **Operate current view** | `ctx.view.close()`, `ctx.view.inputArgs` |
 
-`ctx.openView` opens a `FlowPage` (`ChildPageModel`), which renders a complete flow page internally; `ctx.viewer` opens arbitrary React content.
+`ctx.openView` opens a FlowPage (ChildPageModel) with a full flow; `ctx.viewer` opens arbitrary React content.
 
 ## Notes
 
-- 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.
+- 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.
 
 ## Related
 
-- [ctx.view](./view.md): The currently open view instance.
-- [ctx.model](./model.md): The current model, used to construct a stable `popupUid`.
+- [ctx.view](./view.md): current view instance
+- [ctx.model](./model.md): current model; use for stable popupUid

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

@@ -1,18 +1,18 @@
 # ctx.render()
 
-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.
+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.
 
 ## Use Cases
 
 | Scenario | Description |
-|------|------|
-| **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 |
+|----------|-------------|
+| **JSBlock** | Custom block content (charts, lists, cards, etc.) |
+| **JSField / JSItem / JSColumn** | Custom editable field or table column |
+| **Detail block** | Custom detail field display |
 
-> 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.
+> 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.
 
-## Type Definition
+## Type
 
 ```ts
 render(
@@ -22,27 +22,27 @@ render(
 ```
 
 | Parameter | Type | Description |
-|------|------|------|
-| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to be rendered |
-| `container` | `Element` \| `DocumentFragment` (Optional) | Target rendering container, defaults to `ctx.element` |
+|------------|------|-------------|
+| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to render |
+| `container` | `Element` \| `DocumentFragment` (optional) | Target container; default `ctx.element` |
 
-**Return Value**:
+**Returns**:
 
-- 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`.
+- For **React element**: `ReactDOMClient.Root` (for later `root.render()` updates).
+- For **HTML string** or **DOM node**: `null`.
 
-## vnode Type Description
+## vnode types
 
 | Type | Behavior |
-|------|------|
-| `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. |
+|------|----------|
+| `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 |
 
 ## Examples
 
-### Rendering React Elements (JSX)
+### React (JSX)
 
 ```tsx
 const { Button, Card } = ctx.libs.antd;
@@ -56,26 +56,23 @@ ctx.render(
 );
 ```
 
-### Rendering HTML Strings
+### HTML string
 
 ```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>');
 ```
 
-### Rendering DOM Nodes
+### DOM node
 
 ```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';
@@ -84,31 +81,29 @@ const chart = echarts.init(container);
 chart.setOption({ ... });
 ```
 
-### Specifying a Custom Container
+### Custom container
 
 ```ts
-// Render to a specific DOM element
 const customEl = document.getElementById('my-container');
 ctx.render(<div>Content</div>, customEl);
 ```
 
-### Multiple Calls Will Replace Content
+### Multiple calls 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" will be displayed
+ctx.render(<div>Second</div>);  // Only "Second" is shown
 ```
 
 ## Notes
 
-- **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.
+- **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.
 
 ## Related
 
-- [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.
+- [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()`

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

@@ -1,60 +1,60 @@
 # ctx.request()
 
-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.
+Sends authenticated HTTP requests from RunJS. Requests use the app’s baseURL, token, locale, role, etc., and the app’s interceptors and error handling.
 
 ## Use Cases
 
-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.
+Use whenever RunJS needs to call a remote HTTP API: JSBlock, JSField, JSItem, JSColumn, event flow, linkage, JSAction, etc.
 
-## Type Definition
+## Type
 
 ```typescript
 request(options: RequestOptions): Promise<AxiosResponse<any>>;
 ```
 
-`RequestOptions` extends Axios's `AxiosRequestConfig`:
+`RequestOptions` extends Axios `AxiosRequestConfig`:
 
 ```typescript
 type RequestOptions = AxiosRequestConfig & {
-  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)
+  skipNotify?: boolean | ((error: any) => boolean);  // Skip global error toast on failure
+  skipAuth?: boolean;                                 // Skip auth redirect (e.g. 401 → login)
 };
 ```
 
-## Common Parameters
+## Common parameters
 
 | Parameter | Type | Description |
-|------|------|------|
-| `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) |
+|-----------|------|-------------|
+| `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) |
 
-## Resource Style URL
+## Resource-style URL
 
-NocoBase Resource API supports a shorthand `resource:action` format:
+NocoBase resource API supports `resource:action` shorthand:
 
 | Format | Description | Example |
-|------|------|------|
-| `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` |
+|--------|-------------|---------|
+| `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` |
 
-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.
+Relative URLs are joined with the app baseURL (usually `/api`). For cross-origin, use a full URL and ensure CORS on the target.
 
-## Response Structure
+## Response
 
-The return value is an Axios response object. Common fields include:
+Returns Axios response. Common usage:
 
-- `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`
+- `response.data`: response body
+- List APIs often have `data.data` (records) + `data.meta` (pagination)
+- Single/create/update often have `data.data` as one record
 
 ## Examples
 
-### List Query
+### List
 
 ```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; // Pagination and other info
+const meta = data?.meta;
 ```
 
-### Submit Data
+### Create
 
 ```javascript
 const res = await ctx.request({
   url: 'users:create',
   method: 'post',
-  data: { nickname: 'John Doe', email: 'johndoe@example.com' },
+  data: { nickname: 'John', email: 'john@example.com' },
 });
 
 const newRecord = res?.data?.data;
 ```
 
-### With Filtering and Sorting
+### Filter and sort
 
 ```javascript
 const res = await ctx.request({
@@ -93,16 +93,15 @@ const res = await ctx.request({
 });
 ```
 
-### Skip Error Notification
+### Skip error notify
 
 ```javascript
 const res = await ctx.request({
   url: 'some:action',
   method: 'get',
-  skipNotify: true,  // Do not pop up global message on failure
+  skipNotify: true,
 });
 
-// Or decide whether to skip based on error type
 const res2 = await ctx.request({
   url: 'some:action',
   method: 'get',
@@ -110,9 +109,9 @@ const res2 = await ctx.request({
 });
 ```
 
-### Cross-Origin Request
+### Cross-origin
 
-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:
+For other domains, the target must allow CORS. For its own token, pass in headers:
 
 ```javascript
 const res = await ctx.request({
@@ -124,12 +123,12 @@ const res2 = await ctx.request({
   url: 'https://api.other.com/items',
   method: 'get',
   headers: {
-    Authorization: 'Bearer <target_service_token>',
+    Authorization: 'Bearer <target-token>',
   },
 });
 ```
 
-### Displaying with ctx.render
+### With ctx.render
 
 ```javascript
 const { data } = await ctx.request({
@@ -141,7 +140,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>',
@@ -151,13 +150,13 @@ ctx.render([
 
 ## Notes
 
-- **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.
+- **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.
 
 ## Related
 
-- [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`)
+- [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`)

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

@@ -1,12 +1,12 @@
 # ctx.requireAsync()
 
-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).
+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).
 
 ## Use Cases
 
-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.
+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.
 
-## Type Definition
+## Type
 
 ```ts
 requireAsync<T = any>(url: string): Promise<T>;
@@ -16,40 +16,37 @@ requireAsync<T = any>(url: string): Promise<T>;
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `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. |
+| `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. |
 
-## Return Value
+## Returns
 
-- 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.
+- 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`.
 
-## URL Format Description
+## URL format
 
-- **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.
+- **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.
 
-## Difference from ctx.importAsync()
+## vs ctx.importAsync()
 
-- **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.
+- **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.
 
 ## Examples
 
-### Basic Usage
+### Basic
 
 ```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 Chart
+### ECharts
 
 ```javascript
 const container = document.createElement('div');
@@ -62,13 +59,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
+### Chart.js bar
 
 ```javascript
 async function renderChart() {
@@ -83,7 +80,7 @@ async function renderChart() {
     type: 'bar',
     data: {
       labels: ['A', 'B', 'C'],
-      datasets: [{ label: ctx.t('Quantity'), data: [12, 19, 3] }],
+      datasets: [{ label: ctx.t('Count'), data: [12, 19, 3] }],
     },
   });
 }
@@ -99,12 +96,12 @@ console.log(dayjs?.default || dayjs);
 
 ## Notes
 
-- **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()`.
+- **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()`.
 
 ## Related
 
-- [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.
+- [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