@nocobase/plugin-flow-engine 2.1.0-alpha.1 → 2.1.0-alpha.11

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

@@ -0,0 +1,48 @@
+# 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.
+
+## 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`. |
+
+## Type Definition
+
+```ts
+off(eventName: string, handler: (event?: any) => void): void;
+```
+
+## Examples
+
+### Paired usage in React useEffect
+
+```tsx
+React.useEffect(() => {
+  const handler = (ev) => setValue(ev?.detail ?? '');
+  ctx.on('js-field:value-change', handler);
+  return () => ctx.off('js-field:value-change', handler);
+}, []);
+```
+
+### Unsubscribing from resource events
+
+```ts
+const handler = () => { /* ... */ };
+ctx.resource?.on('refresh', handler);
+// At the appropriate time
+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.
+
+## Related Documents
+
+- [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

@@ -0,0 +1,80 @@
+# 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.
+
+## 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. |
+
+## Type Definition
+
+```ts
+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 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
+
+### Field Two-way Binding (React useEffect + Cleanup)
+
+```tsx
+React.useEffect(() => {
+  const handler = (ev) => setValue(ev?.detail ?? '');
+  ctx.on?.('js-field:value-change', handler);
+  return () => {
+    ctx.off?.('js-field:value-change', handler);
+  };
+}, []);
+```
+
+### 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);
+// During cleanup: ctx.element?.removeEventListener('js-field:value-change', handler);
+```
+
+### Updating UI After Resource Refresh
+
+```ts
+ctx.resource?.on('refresh', () => {
+  const data = ctx.resource?.getData?.();
+  // Update rendering based on data
+});
+```
+
+## Coordination 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)`.
+
+## 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.
+
+## Related Documentation
+
+- [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`)

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

@@ -0,0 +1,120 @@
+# 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.
+
+## 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)`. |
+
+> 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
+
+```ts
+openView(uid: string, options?: OpenViewOptions): Promise<void>
+```
+
+## Parameters
+
+### 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.
+
+### Common options 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. |
+
+## Examples
+
+### Basic Usage: Open a Drawer
+
+```ts
+const popupUid = `${ctx.model.uid}-detail`;
+await ctx.openView(popupUid, {
+  mode: 'drawer',
+  size: 'medium',
+  title: ctx.t('Details'),
+});
+```
+
+### Passing Current Row Context
+
+```ts
+const primaryKey = ctx.collection?.primaryKey || 'id';
+await ctx.openView(`${ctx.model.uid}-1`, {
+  mode: 'dialog',
+  title: ctx.t('Row Details'),
+  params: {
+    filterByTk: ctx.record?.[primaryKey],
+    record: ctx.record,
+  },
+});
+```
+
+### Open via runAction
+
+When a model is configured with an `openView` action (such as association fields or clickable fields), you can call:
+
+```ts
+await ctx.runAction('openView', {
+  navigation: false,
+  mode: 'dialog',
+  collectionName: 'users',
+  filterByTk: ctx.record?.id,
+});
+```
+
+### Injecting Custom Context
+
+```ts
+await ctx.openView(`${ctx.model.uid}-edit`, {
+  mode: 'drawer',
+  filterByTk: ctx.record?.id,
+  defineProperties: {
+    onSaved: {
+      get: () => () => ctx.resource?.refresh?.(),
+      cache: false,
+    },
+  },
+});
+```
+
+## Relationship with ctx.viewer and ctx.view
+
+| Purpose | Recommended Usage |
+|------|----------|
+| **Open a 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` |
+
+`ctx.openView` opens a `FlowPage` (`ChildPageModel`), which renders a complete flow page internally; `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.
+
+## Related
+
+- [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

@@ -0,0 +1,114 @@
+# 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.
+
+## 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 |
+
+> 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 Definition
+
+```ts
+render(
+  vnode: React.ReactElement | Node | DocumentFragment | string,
+  container?: Element | DocumentFragment
+): ReactDOMClient.Root | null;
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `vnode` | `React.ReactElement` \| `Node` \| `DocumentFragment` \| `string` | Content to be rendered |
+| `container` | `Element` \| `DocumentFragment` (Optional) | Target rendering container, defaults to `ctx.element` |
+
+**Return Value**:
+
+- 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 Type Description
+
+| 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. |
+
+## Examples
+
+### Rendering React Elements (JSX)
+
+```tsx
+const { Button, Card } = ctx.libs.antd;
+
+ctx.render(
+  <Card title={ctx.t('Title')}>
+    <Button type="primary" onClick={() => ctx.message.success(ctx.t('Clicked'))}>
+      {ctx.t('Button')}
+    </Button>
+  </Card>
+);
+```
+
+### 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>');
+```
+
+### 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';
+ctx.render(container);
+const chart = echarts.init(container);
+chart.setOption({ ... });
+```
+
+### 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 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" will be displayed
+```
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,163 @@
+# 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.
+
+## 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.
+
+## Type Definition
+
+```typescript
+request(options: RequestOptions): Promise<AxiosResponse<any>>;
+```
+
+`RequestOptions` extends Axios's `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)
+};
+```
+
+## 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) |
+
+## Resource Style URL
+
+NocoBase Resource API supports a shorthand `resource:action` format:
+
+| 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` |
+
+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 Structure
+
+The return value is an Axios response object. Common fields include:
+
+- `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 Query
+
+```javascript
+const { data } = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: { pageSize: 10, page: 1 },
+});
+
+const rows = Array.isArray(data?.data) ? data.data : [];
+const meta = data?.meta; // Pagination and other info
+```
+
+### Submit Data
+
+```javascript
+const res = await ctx.request({
+  url: 'users:create',
+  method: 'post',
+  data: { nickname: 'John Doe', email: 'johndoe@example.com' },
+});
+
+const newRecord = res?.data?.data;
+```
+
+### With Filtering and Sorting
+
+```javascript
+const res = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: {
+    pageSize: 20,
+    sort: ['-createdAt'],
+    filter: { status: 'active' },
+  },
+});
+```
+
+### Skip Error Notification
+
+```javascript
+const res = await ctx.request({
+  url: 'some:action',
+  method: 'get',
+  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',
+  skipNotify: (err) => err?.name === 'CanceledError',
+});
+```
+
+### Cross-Origin Request
+
+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({
+  url: 'https://api.example.com/v1/data',
+  method: 'get',
+});
+
+const res2 = await ctx.request({
+  url: 'https://api.other.com/items',
+  method: 'get',
+  headers: {
+    Authorization: 'Bearer <target_service_token>',
+  },
+});
+```
+
+### Displaying with ctx.render
+
+```javascript
+const { data } = await ctx.request({
+  url: 'users:list',
+  method: 'get',
+  params: { pageSize: 5 },
+});
+const rows = Array.isArray(data?.data) ? data.data : [];
+
+ctx.render([
+  '<div style="padding:12px">',
+  '<h4>' + ctx.t('User List') + '</h4>',
+  '<ul>',
+  ...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
+  '</ul>',
+  '</div>',
+].join(''));
+```
+
+## 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.
+
+## 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`)

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

@@ -0,0 +1,110 @@
+# 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).
+
+## 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.
+
+## Type Definition
+
+```ts
+requireAsync<T = any>(url: string): Promise<T>;
+```
+
+## Parameters
+
+| 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. |
+
+## Return Value
+
+- 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 Description
+
+- **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.
+
+## Difference from 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.
+
+## Examples
+
+### 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 Chart
+
+```javascript
+const container = document.createElement('div');
+container.style.height = '400px';
+container.style.width = '100%';
+ctx.render(container);
+
+const echarts = await ctx.requireAsync('echarts@5/dist/echarts.min.js');
+if (!echarts) throw new Error('ECharts library not loaded');
+
+const chart = echarts.init(container);
+chart.setOption({
+  title: { text: ctx.t('Sales Overview') },
+  series: [{ type: 'pie', data: [{ value: 1, name: ctx.t('A') }] }],
+});
+chart.resize();
+```
+
+### Chart.js Bar Chart
+
+```javascript
+async function renderChart() {
+  const loaded = await ctx.requireAsync('chart.js@4.4.0/dist/chart.umd.min.js');
+  const Chart = loaded?.Chart || loaded?.default?.Chart || loaded?.default;
+  if (!Chart) throw new Error('Chart.js not loaded');
+
+  const container = document.createElement('canvas');
+  ctx.render(container);
+
+  new Chart(container, {
+    type: 'bar',
+    data: {
+      labels: ['A', 'B', 'C'],
+      datasets: [{ label: ctx.t('Quantity'), data: [12, 19, 3] }],
+    },
+  });
+}
+await renderChart();
+```
+
+### dayjs (UMD)
+
+```javascript
+const dayjs = await ctx.requireAsync('dayjs@1/dayjs.min.js');
+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()`.
+
+## 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.