@nocobase/plugin-ai 2.1.0-alpha.26 → 2.1.0-alpha.27

package/dist/ai/docs/nocobase/runjs/context/import-async.md

@@ -0,0 +1,488 @@
+# ctx.importAsync()
+
+Dynamically load **ESM modules** or **CSS** via URL, applicable to various RunJS scenarios. Use `ctx.importAsync()` when third-party ESM libraries are required, and `ctx.requireAsync()` for UMD/AMD libraries. Passing a `.css` address will load and inject the styles into the page.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | Dynamically load ESM libraries such as Vue, ECharts, or Tabulator to implement custom charts, tables, dashboards, etc. |
+| **JSField / JSItem / JSColumn** | Load lightweight ESM utility libraries (e.g., dayjs plugins) to assist in rendering. |
+| **Workflow / Action Events** | Load dependencies on demand before executing business logic. |
+
+## Type Definition
+
+```ts
+importAsync<T = any>(url: string): Promise<T>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `url` | `string` | The address of the ESM module or CSS. Supports shorthand `<package>@<version>` or subpaths `<package>@<version>/<file-path>` (e.g., `vue@3.4.0`, `dayjs@1/plugin/relativeTime.js`), which will be concatenated with the CDN prefix according to the configuration. Full URLs are also supported. When a `.css` file is passed, it will be loaded and injected as a style. For libraries depending on React, you can append `?deps=react@18.2.0,react-dom@18.2.0` to ensure they share the same React instance with the page. |
+
+## Return Value
+
+- A Promise that resolves to the module's namespace object.
+
+## URL Format Description
+
+- **ESM and CSS**: In addition to ESM modules, loading CSS is also supported (pass a `.css` URL to load and inject it into the page).
+- **Shorthand Format**: Defaults to **https://esm.sh** as the CDN prefix if not configured. For example, `vue@3.4.0` actually requests `https://esm.sh/vue@3.4.0`.
+- **?deps**: Libraries that depend on React (such as `@dnd-kit/core`, `react-big-calendar`) should append `?deps=react@18.2.0,react-dom@18.2.0` to avoid conflicts with the page's React instance, which could lead to "Invalid hook call" errors.
+- **Self-hosted CDN**: You can specify an internal network or self-hosted service via environment variables:
+  - **ESM_CDN_BASE_URL**: The base URL for the ESM CDN (default is `https://esm.sh`).
+  - **ESM_CDN_SUFFIX**: Optional suffix (e.g., `/+esm` for jsDelivr).
+  - For self-hosted services, refer to: [nocobase/esm-server](https://github.com/nocobase/esm-server)
+
+## Difference from ctx.requireAsync()
+
+- **ctx.importAsync()**: Loads **ESM modules** and returns the module namespace. Suitable for modern libraries (ESM builds like Vue, dayjs, etc.).
+- **ctx.requireAsync()**: Loads **UMD/AMD** modules or scripts that attach to the global scope. Often used for UMD libraries like ECharts or FullCalendar. If a library provides both ESM and UMD, `ctx.importAsync()` is preferred.
+
+## Examples
+
+### Basic Usage
+
+Demonstrates the most basic usage of dynamically loading ESM modules and CSS by package name or full URL.
+
+```javascript
+const Vue = await ctx.importAsync('vue@3.4.0');
+// Equivalent to loading from https://esm.sh/vue@3.4.0
+
+const relativeTime = await ctx.importAsync('dayjs@1/plugin/relativeTime.js');
+// With subpath (e.g., dayjs plugin)
+
+const pkg = await ctx.importAsync('https://cdn.example.com/my-module.js');
+// Full URL
+
+await ctx.importAsync('https://cdn.example.com/theme.css');
+// Load CSS and inject into the page
+```
+
+### ECharts Example
+
+Use ECharts to draw a sales overview chart with bar and line graphs.
+
+```ts
+// 1. Dynamically load ECharts module
+const echarts = await ctx.importAsync('echarts@5.4.3');
+
+// 2. Create chart container and render
+const chartEl = document.createElement('div');
+chartEl.style.width = '100%';
+chartEl.style.height = '400px';
+ctx.render(chartEl);
+
+// 3. Initialize ECharts instance
+const chart = echarts.init(chartEl);
+
+// 4. Configure chart
+const option = {
+  title: {
+    text: 'Sales Overview',
+    left: 'center',
+  },
+  tooltip: {
+    trigger: 'axis',
+  },
+  legend: {
+    data: ['Sales', 'Profit'],
+    top: '10%',
+  },
+  xAxis: {
+    type: 'category',
+    data: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
+  },
+  yAxis: {
+    type: 'value',
+  },
+  series: [
+    {
+      name: 'Sales',
+      type: 'bar',
+      data: [120, 200, 150, 80, 70, 110],
+    },
+    {
+      name: 'Profit',
+      type: 'line',
+      data: [20, 40, 30, 15, 12, 25],
+    },
+  ],
+};
+
+// 5. Set option and render chart
+chart.setOption(option);
+
+// 6. Optional: Responsive sizing
+window.addEventListener('resize', () => {
+  chart.resize();
+});
+
+// 7. Optional: Event listener
+chart.on('click', (params) => {
+  ctx.message.info(`Clicked ${params.seriesName} on ${params.name}, value: ${params.value}`);
+});
+```
+
+### Tabulator Example
+
+Demonstrates rendering a data table with pagination and row click events in a block using Tabulator.
+
+```ts
+// 1. Load Tabulator styles
+await ctx.importAsync('tabulator-tables@6.2.5/dist/css/tabulator.min.css');
+
+// 2. Dynamically load Tabulator module
+const { TabulatorFull } = await ctx.importAsync('tabulator-tables@6.2.5');
+
+// 3. Create table container and render
+const tableEl = document.createElement('div');
+ctx.render(tableEl);
+
+// 4. Initialize Tabulator table
+const table = new TabulatorFull(tableEl, {
+  data: [
+    { id: 1, name: 'Alice', age: 25, city: 'New York' },
+    { id: 2, name: 'Bob', age: 30, city: 'London' },
+    { id: 3, name: 'Charlie', age: 28, city: 'Paris' },
+  ],
+  columns: [
+    { title: 'ID', field: 'id', width: 80 },
+    { title: 'Name', field: 'name', width: 150 },
+    { title: 'Age', field: 'age', width: 100 },
+    { title: 'City', field: 'city', width: 150 },
+  ],
+  layout: 'fitColumns',
+  pagination: true,
+  paginationSize: 10,
+});
+
+// 5. Optional: Event listener
+table.on('rowClick', (e, row) => {
+  const rowData = row.getData();
+  ctx.message.info(`Row clicked: ${rowData.name}`);
+});
+```
+
+### FullCalendar (ESM) Example
+
+Shows how to load FullCalendar and its plugins via ESM and render a basic monthly view calendar.
+
+```ts
+// 1. Dynamically load FullCalendar core module
+const { Calendar } = await ctx.importAsync('@fullcalendar/core@6.1.20');
+
+// 2. Dynamically load dayGrid plugin
+const dayGridPlugin = await ctx.importAsync('@fullcalendar/daygrid@6.1.20');
+
+// 3. Create calendar container and render
+const calendarEl = document.createElement('div');
+calendarEl.id = 'calendar';
+ctx.render(calendarEl);
+
+// 4. Initialize and render calendar
+const calendar = new Calendar(calendarEl, {
+  plugins: [dayGridPlugin.default || dayGridPlugin],
+  headerToolbar: {
+    left: 'prev,next today',
+    center: 'title',
+    right: 'dayGridMonth',
+  },
+});
+
+calendar.render();
+```
+
+### dnd-kit Simple Drag-and-Drop Example
+
+Uses `@dnd-kit/core` to implement a minimal example of dragging a Box to a target area within a block.
+
+```ts
+// 1. Load React, react-dom, @dnd-kit/core (?deps ensures same React instance to avoid Invalid hook call)
+const React = await ctx.importAsync('react@18.2.0');
+const { createRoot } = await ctx.importAsync('react-dom@18.2.0/client');
+const core = await ctx.importAsync('@dnd-kit/core@6.3.1?deps=react@18.2.0,react-dom@18.2.0');
+const { DndContext, closestCenter, PointerSensor, useSensor, useSensors, useDraggable, useDroppable } = core;
+
+function DraggableBox() {
+  const { attributes, listeners, setNodeRef, transform } = useDraggable({ id: 'box' });
+  const style = {
+    padding: 12,
+    marginBottom: 8,
+    background: '#e6f7ff',
+    cursor: 'grab',
+    transform: transform ? 'translate3d(' + transform.x + 'px,' + transform.y + 'px,0)' : undefined,
+  };
+  return React.createElement('div', { ref: setNodeRef, style, ...attributes, ...listeners }, 'Drag me');
+}
+
+function DropZone() {
+  const { setNodeRef, isOver } = useDroppable({ id: 'zone' });
+  return React.createElement(
+    'div',
+    {
+      ref: setNodeRef,
+      style: { padding: 24, background: isOver ? '#b7eb8f' : '#f5f5f5', borderRadius: 8, minHeight: 80 },
+    },
+    'Drop here',
+  );
+}
+
+function App() {
+  const sensors = useSensors(useSensor(PointerSensor));
+  function onDragEnd(e) {
+    if (e.over && e.over.id === 'zone') ctx.message.success('Dropped in zone');
+  }
+  return React.createElement(
+    DndContext,
+    { sensors, collisionDetection: closestCenter, onDragEnd },
+    React.createElement(
+      'div',
+      { style: { maxWidth: 280 } },
+      React.createElement(DraggableBox),
+      React.createElement(DropZone),
+    ),
+  );
+}
+
+// 2. Render
+ctx.render(<App />);
+```
+
+This example relies only on `@dnd-kit/core` to trigger a notification when a Box is dropped into a specific area, demonstrating the simplest drag-and-drop interaction combining `ctx.importAsync` and React in RunJS.
+
+### dnd-kit Sortable List Example
+
+Implements a vertical sortable list using dnd-kit's core, sortable, and utilities.
+
+```ts
+// 1. Load React and dnd-kit related packages (?deps ensures same React instance)
+const React = await ctx.importAsync('react@18.2.0');
+const { createRoot } = await ctx.importAsync('react-dom@18.2.0/client');
+const dndCore = await ctx.importAsync('@dnd-kit/core@6.3.1?deps=react@18.2.0,react-dom@18.2.0');
+const dndSortable = await ctx.importAsync('@dnd-kit/sortable@10.0.0?deps=react@18.2.0,react-dom@18.2.0');
+const dndUtils = await ctx.importAsync('@dnd-kit/utilities@3.2.2');
+
+const { useState } = React;
+const { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors } = dndCore;
+const {
+  arrayMove,
+  SortableContext,
+  sortableKeyboardCoordinates,
+  verticalListSortingStrategy,
+  useSortable,
+} = dndSortable;
+const { CSS } = dndUtils;
+
+// 2. SortableItem component (must be inside SortableContext)
+function SortableItem(props) {
+  const { id, label } = props;
+  const { attributes, listeners, setNodeRef, transform, transition } = useSortable({ id });
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    padding: '12px 16px',
+    marginBottom: 8,
+    background: '#f5f5f5',
+    borderRadius: 6,
+    cursor: 'grab',
+  };
+  return React.createElement('div', { ref: setNodeRef, style, ...attributes, ...listeners }, label);
+}
+
+// 3. App: DndContext + SortableContext + Drag end handler
+const labels = { 1: 'First', 2: 'Second', 3: 'Third', 4: 'Fourth' };
+function App() {
+  const [items, setItems] = useState([1, 2, 3, 4]);
+  const sensors = useSensors(
+    useSensor(PointerSensor),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  function handleDragEnd(event) {
+    const { active, over } = event;
+    if (over && active.id !== over.id) {
+      setItems((prev) => {
+        const oldIndex = prev.indexOf(active.id);
+        const newIndex = prev.indexOf(over.id);
+        return arrayMove(prev, oldIndex, newIndex);
+      });
+      ctx.message.success('List reordered');
+    }
+  }
+
+  return React.createElement(
+    DndContext,
+    {
+      sensors,
+      collisionDetection: closestCenter,
+      onDragEnd: handleDragEnd,
+    },
+    React.createElement(
+      SortableContext,
+      { items, strategy: verticalListSortingStrategy },
+      React.createElement(
+        'div',
+        { style: { maxWidth: 320 } },
+        items.map((id) => React.createElement(SortableItem, { key: id, id, label: labels[id] })),
+      ),
+    ),
+  );
+}
+
+// 4. Create container and mount React
+const rootEl = document.createElement('div');
+ctx.render(rootEl);
+createRoot(rootEl).render(React.createElement(App));
+```
+
+This example uses `@dnd-kit/core`, `@dnd-kit/sortable`, and `@dnd-kit/utilities` to implement a sortable list that updates its order and displays a "List reordered" message after dragging.
+
+### react-big-calendar Example
+
+Renders a calendar component supporting event display in the current block using `react-big-calendar` and `date-fns` for localization.
+
+```tsx
+// 1. Load styles (ctx.importAsync uses ctx.loadCSS for .css files)
+await ctx.importAsync('react-big-calendar@1.11.4/lib/css/react-big-calendar.css');
+
+// 2. Load React, react-dom, react-big-calendar, date-fns, and locale (ensuring same React instance)
+const React = await ctx.importAsync('react@18.2.0');
+const { Calendar, dateFnsLocalizer } = await ctx.importAsync('react-big-calendar@1.11.4?deps=react@18.2.0,react-dom@18.2.0');
+const { format, parse, startOfWeek, getDay } = await ctx.importAsync('date-fns@2.30.0');
+const enUS = await ctx.importAsync('date-fns@2.30.0/locale/en-US.js');
+
+const localizer = dateFnsLocalizer({
+  format,
+  parse,
+  startOfWeek,
+  getDay,
+  locales: { 'en-US': enUS },
+});
+
+const events = [
+  { title: 'All Day Event', start: new Date(2026, 0, 28), end: new Date(2026, 0, 28), allDay: true },
+  { title: 'Meeting', start: new Date(2026, 0, 29, 10, 0), end: new Date(2026, 0, 29, 11, 0) },
+];
+
+// 3. Render React Calendar
+ctx.render(
+  <Calendar
+    localizer={localizer}
+    events={events}
+    startAccessor="start"
+    endAccessor="end"
+    style={{ height: '80vh' }}
+  />
+);
+```
+
+### frappe-gantt Example
+
+Uses `frappe-gantt` to render a Gantt chart view showing task start/end times and progress.
+
+```ts
+// 1. Dynamically load Gantt styles and constructor
+// Depends on ESM_CDN_BASE_URL (default https://esm.sh), shorthand paths can be used
+await ctx.importAsync('frappe-gantt@1.0.4/dist/frappe-gantt.css');
+const Gantt = await ctx.importAsync('frappe-gantt@1.0.4');
+
+// 2. Prepare task data
+let tasks = [
+  {
+    id: '1',
+    name: 'Redesign website',
+    start: '2016-12-28',
+    end: '2016-12-31',
+    progress: 20,
+  },
+  {
+    id: '2',
+    name: 'Develop new feature',
+    start: '2017-01-01',
+    end: '2017-01-05',
+    progress: 40,
+    dependencies: '1',
+  },
+  {
+    id: '3',
+    name: 'QA & testing',
+    start: '2017-01-06',
+    end: '2017-01-10',
+    progress: 10,
+    dependencies: '2',
+  },
+];
+
+// 3. Create container and render
+const ganttEl = document.createElement('div');
+ganttEl.id = 'gantt';
+ganttEl.style.height = '400px';
+ctx.render(ganttEl);
+
+// 4. Initialize Gantt chart
+let gantt = new Gantt('#gantt', tasks, {
+  view_mode: 'Day', // View granularity: 'Quarter Day' | 'Half Day' | 'Day' | 'Week' | 'Month'
+  language: 'en',
+  bar_height: 24,
+  padding: 18,
+  custom_popup_html(task) {
+    return `
+      <div class="details-container">
+        <h5>${task.name}</h5>
+        <p>Start: ${task._start.toISOString().slice(0, 10)}</p>
+        <p>End: ${task._end.toISOString().slice(0, 10)}</p>
+        <p>Progress: ${task.progress}%</p>
+      </div>
+    `;
+  },
+});
+```
+
+### @asseinfo/react-kanban Example
+
+Utilizes `@asseinfo/react-kanban` to render a basic Kanban board with columns like Backlog and Doing within a block.
+
+```ts
+// 1. Load styles (ctx.importAsync directly loads .css)
+await ctx.importAsync('@asseinfo/react-kanban@2.2.0/dist/styles.css');
+
+// 2. Load React, react-dom, @asseinfo/react-kanban (?deps ensures same React instance)
+const React = await ctx.importAsync('react@18.2.0');
+const { default: Board } = await ctx.importAsync('@asseinfo/react-kanban@2.2.0?deps=react@18.2.0,react-dom@18.2.0');
+
+const board = {
+  columns: [
+    {
+      id: 1,
+      title: 'Backlog',
+      cards: [
+        { id: 1, title: 'Add card', description: 'Add capability to add a card in a column' },
+      ],
+    },
+    {
+      id: 2,
+      title: 'Doing',
+      cards: [
+        { id: 2, title: 'Drag-n-drop support', description: 'Move a card between the columns' },
+      ],
+    },
+  ],
+};
+
+// 4. Mount the board
+ctx.render(<Board initialBoard={board} />);
+```
+
+## Notes
+
+- This feature depends on an external network or CDN. In internal network environments, **ESM_CDN_BASE_URL** must be configured to point to a self-hosted service.
+- When a library provides both ESM and UMD, prefer `ctx.importAsync()` for better module semantics.
+- For libraries depending on React, ensure you append `?deps=react@18.2.0,react-dom@18.2.0`. The version must match the React version used by the page, otherwise, an "Invalid hook call" error may occur.
+
+## Related
+
+- [ctx.requireAsync()](./require-async.md): Load UMD/AMD or globally attached scripts, suitable for UMD libraries like ECharts and FullCalendar.
+- [ctx.render()](./render.md): Render content into a container.

package/dist/ai/docs/nocobase/runjs/context/init-resource.md

@@ -0,0 +1,74 @@
+# ctx.initResource()
+
+**Initializes** the resource for the current context. If `ctx.resource` does not already exist, it creates one of the specified type and binds it to the context; if it already exists, it is used directly. Afterward, it can be accessed via `ctx.resource`.
+
+## Use Cases
+
+Generally used in **JSBlock** (independent block) scenarios. Most blocks, popups, and other components have `ctx.resource` pre-bound and do not require manual calls. JSBlock has no resource by default, so you must call `ctx.initResource(type)` before loading data via `ctx.resource`.
+
+## Type Definition
+
+```ts
+initResource(
+  type: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource'
+): FlowResource;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `string` | Resource type: `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
+
+**Returns**: The resource instance in the current context (i.e., `ctx.resource`).
+
+## Difference from ctx.makeResource()
+
+| Method | Behavior |
+|--------|----------|
+| `ctx.initResource(type)` | Creates and binds if `ctx.resource` does not exist; returns the existing one if it does. Ensures `ctx.resource` is available. |
+| `ctx.makeResource(type)` | Only creates and returns a new instance, does **not** write to `ctx.resource`. Suitable for scenarios requiring multiple independent resources or temporary use. |
+
+## Examples
+
+### List Data (MultiRecordResource)
+
+```ts
+ctx.initResource('MultiRecordResource');
+ctx.resource.setResourceName('users');
+await ctx.resource.refresh();
+const rows = ctx.resource.getData();
+ctx.render(<pre>{JSON.stringify(rows, null, 2)}</pre>);
+```
+
+### Single Record (SingleRecordResource)
+
+```ts
+ctx.initResource('SingleRecordResource');
+ctx.resource.setResourceName('users');
+ctx.resource.setFilterByTk(1); // Specify primary key
+await ctx.resource.refresh();
+const record = ctx.resource.getData();
+```
+
+### Specify Data Source
+
+```ts
+ctx.initResource('MultiRecordResource');
+ctx.resource.setDataSourceKey('main');
+ctx.resource.setResourceName('orders');
+await ctx.resource.refresh();
+```
+
+## Notes
+
+- In most block scenarios (Forms, Tables, Details, etc.) and popups, `ctx.resource` is already pre-bound by the runtime environment, so calling `ctx.initResource` is unnecessary.
+- Manual initialization is only required in contexts like JSBlock where there is no default resource.
+- After initialization, you must call `setResourceName(name)` to specify the collection, and then call `refresh()` to load the data.
+
+## Related
+
+- [ctx.resource](./resource.md) — The resource instance in the current context
+- [ctx.makeResource()](./make-resource.md) — Creates a new resource instance without binding it to `ctx.resource`
+- [MultiRecordResource](../resource/multi-record-resource.md) — Multiple records/List
+- [SingleRecordResource](../resource/single-record-resource.md) — Single record
+- [APIResource](../resource/api-resource.md) — General API resource
+- [SQLResource](../resource/sql-resource.md) — SQL query resource

package/dist/ai/docs/nocobase/runjs/context/libs.md

@@ -0,0 +1,109 @@
+# ctx.libs
+
+`ctx.libs` is the unified namespace for built-in libraries in RunJS, containing commonly used libraries such as React, Ant Design, dayjs, and lodash. **No `import` or asynchronous loading is required**; they can be used directly via `ctx.libs.xxx`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSField / JSItem / JSColumn** | Use React + Ant Design to render UI, dayjs for date handling, and lodash for data processing. |
+| **Formula / Calculation** | Use formula or math for Excel-like formulas and mathematical expression operations. |
+| **Workflow / Linkage Rules** | Call utility libraries like lodash, dayjs, and formula in pure logic scenarios. |
+
+## Built-in Libraries Overview
+
+| Property | Description | Documentation |
+|------|------|------|
+| `ctx.libs.React` | React core, used for JSX and Hooks | [React](https://react.dev/) |
+| `ctx.libs.ReactDOM` | ReactDOM client API (including `createRoot`), used with React for rendering | [React DOM](https://react.dev/reference/react-dom) |
+| `ctx.libs.antd` | Ant Design component library (Button, Card, Table, Form, Input, Modal, etc.) | [Ant Design](https://ant.design/components/overview/) |
+| `ctx.libs.antdIcons` | Ant Design icon library (e.g., PlusOutlined, UserOutlined) | [@ant-design/icons](https://ant.design/components/icon/) |
+| `ctx.libs.dayjs` | Date and time utility library | [dayjs](https://day.js.org/) |
+| `ctx.libs.lodash` | Utility library (get, set, debounce, etc.) | [Lodash](https://lodash.com/docs/) |
+| `ctx.libs.formula` | Excel-like formula function library (SUM, AVERAGE, IF, etc.) | [Formula.js](https://formulajs.info/functions/) |
+| `ctx.libs.math` | Mathematical expression and calculation library | [Math.js](https://mathjs.org/docs/) |
+
+## Top-level Aliases
+
+For compatibility with legacy code, some libraries are also exposed at the top level: `ctx.React`, `ctx.ReactDOM`, `ctx.antd`, and `ctx.dayjs`. **It is recommended to consistently use `ctx.libs.xxx`** for easier maintenance and documentation searching.
+
+## Lazy Loading
+
+`lodash`, `formula`, and `math` use **lazy loading**: a dynamic import is triggered only when `ctx.libs.lodash` is accessed for the first time, and the cache is reused thereafter. `React`, `antd`, `dayjs`, and `antdIcons` are pre-configured by the context and are available immediately.
+
+## Examples
+
+### Rendering with React and Ant Design
+
+```tsx
+const { Button, Card } = ctx.libs.antd;
+
+ctx.render(
+  <Card title="Title">
+    <Button type="primary">Click</Button>
+  </Card>
+);
+```
+
+### Using Hooks
+
+```tsx
+const { React } = ctx.libs;
+const { useState } = React;
+const { Button } = ctx.libs.antd;
+
+const App = () => {
+  const [count, setCount] = useState(0);
+  return <Button onClick={() => setCount((c) => c + 1)}>{count}</Button>;
+};
+ctx.render(<App />);
+```
+
+### Using Icons
+
+```tsx
+const { Button } = ctx.libs.antd;
+const { UserOutlined, HeartOutlined } = ctx.libs.antdIcons;
+
+ctx.render(<Button icon={<UserOutlined />}>User</Button>);
+```
+
+### Date Processing with dayjs
+
+```ts
+const now = ctx.libs.dayjs();
+const formatted = now.format('YYYY-MM-DD HH:mm:ss');
+ctx.message.info(formatted);
+```
+
+### Utility Functions with lodash
+
+```ts
+const user = { profile: { name: 'Alice' } };
+const name = ctx.libs.lodash.get(user, 'profile.name', 'Unknown');
+```
+
+### Formula Calculations
+
+```ts
+const values = [1, 2, 3, 4];
+const sum = ctx.libs.formula.SUM(values);
+const avg = ctx.libs.formula.AVERAGE(values);
+```
+
+### Mathematical Expressions with math.js
+
+```ts
+const result = ctx.libs.math.evaluate('2 + 3 * 4');
+// result === 14
+```
+
+## Notes
+
+- **Mixing with ctx.importAsync**: If an external React is loaded via `ctx.importAsync('react@19')`, JSX will use that instance. In this case, **do not** mix it with `ctx.libs.antd`. Ant Design must be loaded to match that React version (e.g., `ctx.importAsync('antd@5.x')`, `ctx.importAsync('@ant-design/icons@5.x')`).
+- **Multiple React Instances**: If "Invalid hook call" occurs or the hook dispatcher is null, it is usually caused by multiple React instances. Before reading `ctx.libs.React` or calling Hooks, execute `await ctx.importAsync('react@version')` first to ensure the same React instance is shared with the page.
+
+## Related
+
+- [ctx.importAsync()](./import-async.md) - Load external ESM modules on demand (e.g., specific versions of React, Vue)
+- [ctx.render()](./render.md) - Render content to a container