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

package/dist/ai/docs/meta.json

@@ -0,0 +1,6 @@
+[
+  {
+    "module": "runjs",
+    "description": "RunJS contexts and runtime APIs"
+  }
+]

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

@@ -0,0 +1,90 @@
+# ctx.blockModel
+
+The parent block model (BlockModel instance) that hosts the current JS field / JS block. In JSField, JSItem, JSColumn, etc., `ctx.blockModel` refers to the form block or table block that hosts the current JS logic; in a standalone JSBlock it may be `null` or the same as `ctx.model`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField** | Access parent form block's `form`, `collection`, `resource` for linkage or validation |
+| **JSItem** | Access parent table/form block's resource and collection in sub-table items |
+| **JSColumn** | Access parent table block's `resource` (e.g. `getSelectedRows`), `collection` |
+| **Form actions / event flow** | Use `form` for pre-submit validation, `resource` for refresh, etc. |
+
+> Note: `ctx.blockModel` is only available in RunJS contexts that have a parent block; in a standalone JSBlock (no parent form/table) it may be `null`—check before use.
+
+## Type
+
+```ts
+blockModel: BlockModel | FormBlockModel | TableBlockModel | CollectionBlockModel | DataBlockModel | null;
+```
+
+The exact type depends on the parent block: form blocks are usually `FormBlockModel` / `EditFormModel`, table blocks are usually `TableBlockModel`.
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `uid` | `string` | Block model unique id |
+| `collection` | `Collection` | Collection bound to the block |
+| `resource` | `Resource` | Resource instance (`SingleRecordResource` / `MultiRecordResource`, etc.) |
+| `form` | `FormInstance` | Form block: Ant Design Form instance (`getFieldsValue`, `validateFields`, `setFieldsValue`, etc.) |
+| `emitter` | `EventEmitter` | Event emitter; can listen to `formValuesChange`, `onFieldReset`, etc. |
+
+## Relation to ctx.model, ctx.form
+
+| Need | Recommended |
+|------|-------------|
+| **Parent block of current JS** | `ctx.blockModel` |
+| **Read/write form fields** | `ctx.form` (same as `ctx.blockModel?.form`; more convenient in form blocks) |
+| **Model for current execution context** | `ctx.model` (field model in JSField, block model in JSBlock) |
+
+In JSField, `ctx.model` is the field model and `ctx.blockModel` is the form/table block that hosts it; `ctx.form` is usually `ctx.blockModel.form`.
+
+## Examples
+
+### Table: get selected rows and process
+
+```ts
+const rows = ctx.blockModel?.resource?.getSelectedRows?.() || [];
+if (rows.length === 0) {
+  ctx.message.warning('Please select data first');
+  return;
+}
+```
+
+### Form: validate and refresh
+
+```ts
+if (ctx.blockModel?.form) {
+  await ctx.blockModel.form.validateFields();
+  await ctx.blockModel.resource?.refresh?.();
+}
+```
+
+### Listen to form changes
+
+```ts
+ctx.blockModel?.emitter?.on?.('formValuesChange', (payload) => {
+  // React to latest form values or re-render
+});
+```
+
+### Trigger block re-render
+
+```ts
+ctx.blockModel?.rerender?.();
+```
+
+## Notes
+
+- In a **standalone JSBlock** (no parent form/table), `ctx.blockModel` may be `null`; use optional chaining: `ctx.blockModel?.resource?.refresh?.()`.
+- In **JSField / JSItem / JSColumn**, `ctx.blockModel` is the form or table block that hosts the field; in **JSBlock**, it may be the block itself or an ancestor, depending on hierarchy.
+- `resource` exists only on data blocks; `form` exists only on form blocks; table blocks usually have no `form`.
+
+## Related
+
+- [ctx.model](./model.md): model for current execution context
+- [ctx.form](./form.md): form instance, common in form blocks
+- [ctx.resource](./resource.md): resource instance (same as `ctx.blockModel?.resource` when present)
+- [ctx.getModel()](./get-model.md): get another block model by uid

package/dist/ai/docs/runjs/context/collection-field.md

@@ -0,0 +1,130 @@
+# ctx.collectionField
+
+The collection field (CollectionField) instance for the current RunJS context; used to access field metadata, type, validation rules, and association info. Only present when the field is bound to a collection definition; custom/virtual fields may have `null`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField** | Use `interface`, `enum`, `targetCollection`, etc. for linkage or validation |
+| **JSItem** | Access metadata of the column’s field in sub-table items |
+| **JSColumn** | Choose render by `collectionField.interface`, or use `targetCollection` |
+
+> Note: `ctx.collectionField` is only available when the field is bound to a collection; in standalone JSBlock or actions with no field binding it is usually `undefined`—check before use.
+
+## Type
+
+```ts
+collectionField: CollectionField | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Field name (e.g. `status`, `userId`) |
+| `title` | `string` | Field title (i18n) |
+| `type` | `string` | Data type (`string`, `integer`, `belongsTo`, etc.) |
+| `interface` | `string` | UI type (`input`, `select`, `m2o`, `o2m`, `m2m`, etc.) |
+| `collection` | `Collection` | Field’s collection |
+| `targetCollection` | `Collection` | Target collection for association fields only |
+| `target` | `string` | Target collection name (association) |
+| `enum` | `array` | Enum options (select, radio, etc.) |
+| `defaultValue` | `any` | Default value |
+| `collectionName` | `string` | Collection name |
+| `foreignKey` | `string` | Foreign key (e.g. belongsTo) |
+| `sourceKey` | `string` | Source key (e.g. hasMany) |
+| `targetKey` | `string` | Target key |
+| `fullpath` | `string` | Full path (e.g. `main.users.status`) for API/variables |
+| `resourceName` | `string` | Resource name (e.g. `users.status`) |
+| `readonly` | `boolean` | Read-only |
+| `titleable` | `boolean` | Can be used as title |
+| `validation` | `object` | Validation config |
+| `uiSchema` | `object` | UI config |
+| `targetCollectionTitleField` | `CollectionField` | Title field of target collection (association) |
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `isAssociationField(): boolean` | Whether it is an association (belongsTo, hasMany, hasOne, belongsToMany, etc.) |
+| `isRelationshipField(): boolean` | Whether it is a relationship (o2o, m2o, o2m, m2m, etc.) |
+| `getComponentProps(): object` | Default props for the field component |
+| `getFields(): CollectionField[]` | Fields of target collection (association only) |
+| `getFilterOperators(): object[]` | Filter operators (e.g. `$eq`, `$ne`) |
+
+## Examples
+
+### Branch by field type
+
+```ts
+if (!ctx.collectionField) return null;
+const { interface: iface } = ctx.collectionField;
+if (['m2o', 'o2m', 'm2m'].includes(iface)) {
+  const target = ctx.collectionField.targetCollection;
+  // ...
+} else if (iface === 'select' || iface === 'radioGroup') {
+  const options = ctx.collectionField.enum || [];
+  // ...
+}
+```
+
+### Check association and use target collection
+
+```ts
+if (ctx.collectionField?.isAssociationField()) {
+  const targetCol = ctx.collectionField.targetCollection;
+  const titleField = targetCol?.titleCollectionField?.name;
+  // ...
+}
+```
+
+### Get enum options
+
+```ts
+const options = ctx.collectionField?.enum ?? [];
+const labels = options.map((o) => (typeof o === 'object' ? o.label : o));
+```
+
+### Conditional render by readonly
+
+```ts
+const { Input } = ctx.libs.antd;
+if (ctx.collectionField?.readonly) {
+  ctx.render(<span>{ctx.getValue?.() ?? '-'}</span>);
+} else {
+  ctx.render(<Input onChange={(e) => ctx.setValue?.(e.target.value)} />);
+}
+```
+
+### Title field of target collection
+
+```ts
+const titleField = ctx.collectionField?.targetCollectionTitleField;
+const titleKey = titleField?.name ?? 'title';
+const assocValue = ctx.getValue?.() ?? ctx.record?.[ctx.collectionField?.name];
+const label = assocValue?.[titleKey];
+```
+
+## Relation to ctx.collection
+
+| Need | Recommended |
+|------|-------------|
+| **Collection of current field** | `ctx.collectionField?.collection` or `ctx.collection` |
+| **Field metadata (name, type, interface, enum, etc.)** | `ctx.collectionField` |
+| **Target collection** | `ctx.collectionField?.targetCollection` |
+
+`ctx.collection` is usually the block’s collection; `ctx.collectionField` is the field definition; they can differ in sub-tables and associations.
+
+## Notes
+
+- In **JSBlock**, **JSAction (no field binding)**, `ctx.collectionField` is usually `undefined`; use optional chaining.
+- Custom JS fields not bound to a collection field may have `ctx.collectionField` as `null`.
+- `targetCollection` exists only for association fields (m2o, o2m, m2m); `enum` only for select, radioGroup, etc.
+
+## Related
+
+- [ctx.collection](./collection.md): collection for current context
+- [ctx.model](./model.md): model for current execution context
+- [ctx.blockModel](./block-model.md): parent block
+- [ctx.getValue()](./get-value.md), [ctx.setValue()](./set-value.md): read/write current field value

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

@@ -0,0 +1,100 @@
+# ctx.collection
+
+The collection (data table) instance associated with the current RunJS execution context; used to access collection metadata, field definitions, primary key, etc. Usually from `ctx.blockModel.collection` or `ctx.collectionField?.collection`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Block-bound collection; access `name`, `getFields`, `filterTargetKey`, etc. |
+| **JSField / JSItem / JSColumn** | Collection of current field or parent block; get field list, primary key, etc. |
+| **Table column / detail block** | Render by collection structure, pass `filterByTk` when opening popup, etc. |
+
+> Note: `ctx.collection` is available when the context is bound to a data block, form block, or table block; a standalone JSBlock with no bound collection may have `null`—check before use.
+
+## Type
+
+```ts
+collection: Collection | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Collection name (e.g. `users`, `orders`) |
+| `title` | `string` | Collection title (i18n) |
+| `filterTargetKey` | `string \| string[]` | Primary key field name(s); used for `filterByTk`, `getFilterByTK` |
+| `dataSourceKey` | `string` | Data source key (e.g. `main`) |
+| `dataSource` | `DataSource` | Data source instance |
+| `template` | `string` | Collection template (e.g. `general`, `file`, `tree`) |
+| `titleableFields` | `CollectionField[]` | Fields that can be used as title |
+| `titleCollectionField` | `CollectionField` | Title field instance |
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `getFields(): CollectionField[]` | All fields (including inherited) |
+| `getField(name: string): CollectionField \| undefined` | Single field by name |
+| `getFieldByPath(path: string): CollectionField \| undefined` | Field by path (supports association, e.g. `user.name`) |
+| `getAssociationFields(types?): CollectionField[]` | Association fields; `types` e.g. `['one']`, `['many']` |
+| `getFilterByTK(record): any` | Primary key value from record for API `filterByTk` |
+
+## Relation to ctx.collectionField, ctx.blockModel
+
+| Need | Recommended |
+|------|-------------|
+| **Collection for current context** | `ctx.collection` (same as `ctx.blockModel?.collection` or `ctx.collectionField?.collection`) |
+| **Collection of current field** | `ctx.collectionField?.collection` |
+| **Target collection of association** | `ctx.collectionField?.targetCollection` |
+
+In sub-tables etc., `ctx.collection` may be the association target; in normal form/table it is usually the block’s collection.
+
+## Examples
+
+### Get primary key and open popup
+
+```ts
+const primaryKey = ctx.collection?.filterTargetKey ?? 'id';
+await ctx.openView(popupUid, {
+  mode: 'dialog',
+  params: {
+    filterByTk: ctx.record?.[primaryKey],
+    record: ctx.record,
+  },
+});
+```
+
+### Iterate fields for validation or linkage
+
+```ts
+const fields = ctx.collection?.getFields() ?? [];
+const requiredFields = fields.filter((f) => f.options?.required);
+for (const f of requiredFields) {
+  const v = ctx.form?.getFieldValue(f.name);
+  if (v == null || v === '') {
+    ctx.message.warning(`${f.title} is required`);
+    return;
+  }
+}
+```
+
+### Get association fields
+
+```ts
+const oneToMany = ctx.collection?.getAssociationFields(['many']) ?? [];
+// For sub-tables, association resources, etc.
+```
+
+## Notes
+
+- `filterTargetKey` is the collection’s primary key field name; some collections use `string[]` composite keys; fallback is often `'id'`.
+- In **sub-tables, association fields**, `ctx.collection` may point to the association target, different from `ctx.blockModel.collection`.
+- `getFields()` merges inherited collection fields; local fields override inherited ones with the same name.
+
+## Related
+
+- [ctx.collectionField](./collection-field.md): current field’s collection field definition
+- [ctx.blockModel](./block-model.md): parent block that hosts current JS; has `collection`
+- [ctx.model](./model.md): current model; may have `collection`

package/dist/ai/docs/runjs/context/data-source-manager.md

@@ -0,0 +1,110 @@
+# ctx.dataSourceManager
+
+The data source manager (`DataSourceManager` instance) for managing and accessing multiple data sources (e.g. main `main`, logging `logging`). Use when you have multiple data sources or need cross–data-source metadata access.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Multiple data sources** | Enumerate all data sources, get one by key |
+| **Cross–data-source access** | When context doesn’t know the data source, access by “data source key + collection name” |
+| **Field by full path** | Get field definition with path format `dataSourceKey.collectionName.fieldPath` |
+
+> Note: If you only work with the current data source, use `ctx.dataSource`; use `ctx.dataSourceManager` when you need to enumerate or switch data sources.
+
+## Type
+
+```ts
+dataSourceManager: DataSourceManager;
+
+class DataSourceManager {
+  constructor();
+
+  addDataSource(ds: DataSource | DataSourceOptions): void;
+  upsertDataSource(ds: DataSource | DataSourceOptions): void;
+  removeDataSource(key: string): void;
+  clearDataSources(): void;
+
+  getDataSources(): DataSource[];
+  getDataSource(key: string): DataSource | undefined;
+
+  getCollection(dataSourceKey: string, collectionName: string): Collection | undefined;
+  getCollectionField(fieldPathWithDataSource: string): CollectionField | undefined;
+}
+```
+
+## Relation to ctx.dataSource
+
+| Need | Recommended |
+|------|-------------|
+| **Single data source for context** | `ctx.dataSource` |
+| **Entry to all data sources** | `ctx.dataSourceManager` |
+| **List or switch data sources** | `ctx.dataSourceManager.getDataSources()` / `getDataSource(key)` |
+| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
+| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Examples
+
+### Get a data source
+
+```ts
+const mainDS = ctx.dataSourceManager.getDataSource('main');
+const collections = mainDS?.getCollections();
+```
+
+### Cross–data-source collection metadata
+
+```ts
+const users = ctx.dataSourceManager.getCollection('main', 'users');
+const orders = ctx.dataSourceManager.getCollection('main', 'orders');
+
+const primaryKey = users?.filterTargetKey ?? 'id';
+```
+
+### Field by full path
+
+```ts
+// Format: dataSourceKey.collectionName.fieldPath
+const field = ctx.dataSourceManager.getCollectionField('main.users.profile.avatar');
+
+const userNameField = ctx.dataSourceManager.getCollectionField('main.orders.createdBy.name');
+```
+
+### Iterate all data sources
+
+```ts
+const dataSources = ctx.dataSourceManager.getDataSources();
+for (const ds of dataSources) {
+  ctx.logger.info(`Data source: ${ds.key}, display: ${ds.displayName}`);
+  const collections = ds.getCollections();
+  for (const col of collections) {
+    ctx.logger.info(`  - Collection: ${col.name}`);
+  }
+}
+```
+
+### Dynamic data source from variable
+
+```ts
+const dsKey = ctx.getVar('dataSourceKey') ?? 'main';
+const collectionName = ctx.getVar('collectionName') ?? 'users';
+const col = ctx.dataSourceManager.getCollection(dsKey, collectionName);
+if (col) {
+  const fields = col.getFields();
+  // ...
+}
+```
+
+## Notes
+
+- `getCollectionField` path format is `dataSourceKey.collectionName.fieldPath`; first segment is data source key, then collection name and field path.
+- `getDataSource(key)` returns `undefined` if the data source doesn’t exist—check before use.
+- `addDataSource` throws if key already exists; `upsertDataSource` overwrites or adds.
+
+## Related
+
+- [ctx.dataSource](./data-source.md): current data source instance
+- [ctx.collection](./collection.md): collection for current context
+- [ctx.collectionField](./collection-field.md): current field’s collection field definition

package/dist/ai/docs/runjs/context/data-source.md

@@ -0,0 +1,128 @@
+# ctx.dataSource
+
+The data source instance (`DataSource`) bound to the current RunJS context; used to access collections, field metadata, and collection config **within that data source**. Usually the current page/block’s data source (e.g. main `main`).
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Single data source** | Get collections, field metadata when the current data source is known |
+| **Collection management** | Get/add/update/remove collections in the current data source |
+| **Field by path** | Get field definition by `collectionName.fieldPath` (supports association path) |
+
+> Note: `ctx.dataSource` is the single data source for the current context; to enumerate or access other data sources use [ctx.dataSourceManager](./data-source-manager.md).
+
+## Type
+
+```ts
+dataSource: DataSource;
+
+class DataSource {
+  constructor(options?: Record<string, any>);
+
+  get flowEngine(): FlowEngine;
+  get displayName(): string;
+  get key(): string;
+  get name(): string;
+
+  getCollections(): Collection[];
+  getCollection(name: string): Collection | undefined;
+  getAssociation(associationName: string): CollectionField | undefined;
+
+  addCollection(collection: Collection | CollectionOptions): void;
+  updateCollection(newOptions: CollectionOptions): void;
+  upsertCollection(options: CollectionOptions): Collection | undefined;
+  upsertCollections(collections: CollectionOptions[], options?: { clearFields?: boolean }): void;
+  removeCollection(name: string): void;
+  clearCollections(): void;
+
+  getCollectionField(fieldPath: string): CollectionField | undefined;
+}
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | Data source key (e.g. `main`) |
+| `name` | `string` | Same as key |
+| `displayName` | `string` | Display name (i18n) |
+| `flowEngine` | `FlowEngine` | Current FlowEngine instance |
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `getCollections()` | All collections in this data source (sorted, hidden filtered) |
+| `getCollection(name)` | Collection by name; `name` can be `collectionName.fieldName` for association target |
+| `getAssociation(associationName)` | Association field by `collectionName.fieldName` |
+| `getCollectionField(fieldPath)` | Field by `collectionName.fieldPath`; supports paths like `users.profile.avatar` |
+
+## Relation to ctx.dataSourceManager
+
+| Need | Recommended |
+|------|-------------|
+| **Single data source for context** | `ctx.dataSource` |
+| **Entry to all data sources** | `ctx.dataSourceManager` |
+| **Collection in current data source** | `ctx.dataSource.getCollection(name)` |
+| **Collection in another data source** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Field in current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Examples
+
+### Get collections and fields
+
+```ts
+const collections = ctx.dataSource.getCollections();
+
+const users = ctx.dataSource.getCollection('users');
+const primaryKey = users?.filterTargetKey ?? 'id';
+
+const field = ctx.dataSource.getCollectionField('users.profile.avatar');
+const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
+```
+
+### Get association field
+
+```ts
+const rolesField = ctx.dataSource.getAssociation('users.roles');
+if (rolesField?.isAssociationField()) {
+  const targetCol = rolesField.targetCollection;
+  // ...
+}
+```
+
+### Iterate collections
+
+```ts
+const collections = ctx.dataSource.getCollections();
+for (const col of collections) {
+  const fields = col.getFields();
+  const requiredFields = fields.filter((f) => f.options?.required);
+  // ...
+}
+```
+
+### Validation or dynamic UI from field metadata
+
+```ts
+const field = ctx.dataSource.getCollectionField('users.status');
+if (field) {
+  const options = field.enum ?? [];
+  const operators = field.getFilterOperators();
+  // ...
+}
+```
+
+## Notes
+
+- `getCollectionField(fieldPath)` uses path format `collectionName.fieldPath`; first segment is collection name, rest is field path (supports association, e.g. `user.name`).
+- `getCollection(name)` supports `collectionName.fieldName` and returns the association target collection.
+- In RunJS, `ctx.dataSource` is usually determined by the current block/page; if there is no bound data source it may be `undefined`—check before use.
+
+## Related
+
+- [ctx.dataSourceManager](./data-source-manager.md): manager for all data sources
+- [ctx.collection](./collection.md): collection for current context
+- [ctx.collectionField](./collection-field.md): current field’s collection field definition

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

@@ -0,0 +1,98 @@
+# ctx.element
+
+The ElementProxy instance for the sandbox DOM container; it is the default render target of `ctx.render()`. Available in JSBlock, JSField, JSItem, JSColumn, and other contexts that have a render container.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | Block’s DOM container for custom content |
+| **JSField / JSItem / FormJSFieldItem** | Field/item render container (often a `<span>`) |
+| **JSColumn** | Table cell DOM container for custom column content |
+
+> Note: `ctx.element` is only available in RunJS contexts that have a render container; in contexts without UI (e.g. pure backend) it may be `undefined`—check before use.
+
+## Type
+
+```typescript
+element: ElementProxy | undefined;
+
+class ElementProxy {
+  __el: HTMLElement;  // Internal native DOM (only for specific cases)
+  innerHTML: string;  // Read/write sanitized with DOMPurify
+  outerHTML: string;
+  appendChild(child: HTMLElement | string): void;
+  // Other HTMLElement methods passed through (not recommended)
+}
+```
+
+## Security
+
+**Recommended: do all rendering via `ctx.render()`.** Do not use `ctx.element`’s DOM APIs directly (e.g. `innerHTML`, `appendChild`, `querySelector`).
+
+### Why use ctx.render()
+
+| Benefit | Description |
+|---------|-------------|
+| **Security** | Centralized control, avoids XSS and unsafe DOM use |
+| **React** | Full JSX, components, and lifecycle |
+| **Context** | Inherits app ConfigProvider, theme, etc. |
+| **Conflicts** | Manages React root create/unmount, avoids multiple instances |
+
+### ❌ Not recommended: direct ctx.element use
+
+```ts
+ctx.element.innerHTML = '<div>Content</div>';
+ctx.element.appendChild(node);
+ctx.element.querySelector('.class');
+```
+
+> `ctx.element.innerHTML` is deprecated; use `ctx.render()` instead.
+
+### ✅ Recommended: ctx.render()
+
+```ts
+const { Button, Card } = ctx.libs.antd;
+ctx.render(
+  <Card title={ctx.t('Welcome')}>
+    <Button type="primary">Click</Button>
+  </Card>
+);
+
+ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
+
+const div = document.createElement('div');
+div.textContent = ctx.t('Hello');
+ctx.render(div);
+```
+
+## Exception: popover anchor
+
+When you need the current element as a popover anchor, use `ctx.element?.__el` as the native DOM `target`:
+
+```ts
+await ctx.viewer.popover({
+  target: ctx.element?.__el,
+  content: <div>Popover content</div>,
+});
+```
+
+> Use `__el` only for this “current container as anchor” case; do not touch DOM otherwise.
+
+## Relation to ctx.render
+
+- `ctx.render(vnode)` without a `container` argument renders into `ctx.element`.
+- If there is no `ctx.element` and no `container`, an error is thrown.
+- You can pass a container: `ctx.render(vnode, customContainer)`.
+
+## Notes
+
+- Treat `ctx.element` as the internal container for `ctx.render()`; avoid reading or mutating it directly.
+- In contexts without a render container, `ctx.element` is `undefined`; ensure a container exists or pass `container` to `ctx.render()`.
+- ElementProxy’s `innerHTML`/`outerHTML` are sanitized with DOMPurify, but prefer `ctx.render()` for all rendering.
+
+## Related
+
+- [ctx.render](./render.md): render into container
+- [ctx.view](./view.md): current view controller
+- [ctx.modal](./modal.md): modal APIs