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

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

@@ -0,0 +1,90 @@
+# ctx.blockModel
+
+The parent block model (BlockModel instance) where the current JS Field / JS Block is located. In scenarios such as JSField, JSItem, and JSColumn, `ctx.blockModel` points to the form block or table block carrying the current JS logic. In a standalone JSBlock, it may be `null` or the same as `ctx.model`.
+
+## Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Access the `form`, `collection`, and `resource` of the parent form block within a form field to implement linkage or validation. |
+| **JSItem** | Access the resource and collection information of the parent table/form block within a sub-table item. |
+| **JSColumn** | Access the `resource` (e.g., `getSelectedRows`) and `collection` of the parent table block within a table column. |
+| **Form Actions / FlowEngine** | Access `form` for pre-submission validation, `resource` for refreshing, etc. |
+
+> Note: `ctx.blockModel` is only available in RunJS contexts where a parent block exists. In standalone JSBlocks (without a parent form/table), it may be `null`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```ts
+blockModel: BlockModel | FormBlockModel | TableBlockModel | CollectionBlockModel | DataBlockModel | null;
+```
+
+The specific type depends on the parent block type: form blocks are mostly `FormBlockModel` or `EditFormModel`, while table blocks are mostly `TableBlockModel`.
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `uid` | `string` | Unique identifier of the block model. |
+| `collection` | `Collection` | The collection bound to the current block. |
+| `resource` | `Resource` | The resource instance used by the block (`SingleRecordResource` / `MultiRecordResource`, etc.). |
+| `form` | `FormInstance` | Form Block: Ant Design Form instance, supporting `getFieldsValue`, `validateFields`, `setFieldsValue`, etc. |
+| `emitter` | `EventEmitter` | Event emitter, used to listen for `formValuesChange`, `onFieldReset`, etc. |
+
+## Relationship with ctx.model and ctx.form
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Parent block of the current JS** | `ctx.blockModel` |
+| **Read/Write form fields** | `ctx.form` (equivalent to `ctx.blockModel?.form`, more convenient in form blocks) |
+| **Model of the current execution context** | `ctx.model` (Field model in JSField, Block model in JSBlock) |
+
+In a JSField, `ctx.model` is the field model, and `ctx.blockModel` is the form or table block carrying that field; `ctx.form` is typically `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 Scenario: Validate and Refresh
+
+```ts
+if (ctx.blockModel?.form) {
+  await ctx.blockModel.form.validateFields();
+  await ctx.blockModel.resource?.refresh?.();
+}
+```
+
+### Listen for Form Changes
+
+```ts
+ctx.blockModel?.emitter?.on?.('formValuesChange', (payload) => {
+  // Implement linkage or re-rendering based on the latest form values
+});
+```
+
+### Trigger Block Re-render
+
+```ts
+ctx.blockModel?.rerender?.();
+```
+
+## Notes
+
+- In a **standalone JSBlock** (without a parent form or table block), `ctx.blockModel` may be `null`. It is recommended to use optional chaining when accessing its properties: `ctx.blockModel?.resource?.refresh?.()`.
+- In **JSField / JSItem / JSColumn**, `ctx.blockModel` refers to the form or table block carrying the current field. In a **JSBlock**, it may be itself or an upper-level block, depending on the actual hierarchy.
+- `resource` only exists in data blocks; `form` only exists in form blocks. Table blocks typically do not have a `form`.
+
+## Related
+
+- [ctx.model](./model.md): The model of the current execution context.
+- [ctx.form](./form.md): Form instance, commonly used in form blocks.
+- [ctx.resource](./resource.md): Resource instance (equivalent to `ctx.blockModel?.resource`, use directly if available).
+- [ctx.getModel()](./get-model.md): Get other block models by UID.

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

@@ -0,0 +1,132 @@
+# ctx.collectionField
+
+The `CollectionField` instance associated with the current RunJS execution context, used to access field metadata, types, validation rules, and association information. It only exists when the field is bound to a collection definition; custom/virtual fields may be `null`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Perform linkage or validation in form fields based on `interface`, `enum`, `targetCollection`, etc. |
+| **JSItem** | Access metadata of the field corresponding to the current column in sub-table items. |
+| **JSColumn** | Select rendering methods based on `collectionField.interface` or access `targetCollection` in table columns. |
+
+> Note: `ctx.collectionField` is only available when the field is bound to a Collection definition; it is usually `undefined` in scenarios like JSBlock independent blocks or action events without field binding. It is recommended to check for null values before use.
+
+## Type Definition
+
+```ts
+collectionField: CollectionField | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `name` | `string` | Field name (e.g., `status`, `userId`) |
+| `title` | `string` | Field title (including internationalization) |
+| `type` | `string` | Field data type (`string`, `integer`, `belongsTo`, etc.) |
+| `interface` | `string` | Field interface type (`input`, `select`, `m2o`, `o2m`, `m2m`, etc.) |
+| `collection` | `Collection` | The collection the field belongs to |
+| `targetCollection` | `Collection` | The target collection of the association field (only for association types) |
+| `target` | `string` | Target collection name (for association fields) |
+| `enum` | `array` | Enumeration options (select, radio, etc.) |
+| `defaultValue` | `any` | Default value |
+| `collectionName` | `string` | Name of the collection it belongs to |
+| `foreignKey` | `string` | Foreign key field name (belongsTo, etc.) |
+| `sourceKey` | `string` | Association source key (hasMany, etc.) |
+| `targetKey` | `string` | Association target key |
+| `fullpath` | `string` | Full path (e.g., `main.users.status`), used for API or variable references |
+| `resourceName` | `string` | Resource name (e.g., `users.status`) |
+| `readonly` | `boolean` | Whether it is read-only |
+| `titleable` | `boolean` | Whether it can be displayed as a title |
+| `validation` | `object` | Validation rule configuration |
+| `uiSchema` | `object` | UI configuration |
+| `targetCollectionTitleField` | `CollectionField` | The title field of the target collection (for association fields) |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `isAssociationField(): boolean` | Whether it is an association field (belongsTo, hasMany, hasOne, belongsToMany, etc.) |
+| `isRelationshipField(): boolean` | Whether it is a relationship field (including o2o, m2o, o2m, m2m, etc.) |
+| `getComponentProps(): object` | Get the default props of the field component |
+| `getFields(): CollectionField[]` | Get the field list of the target collection (association fields only) |
+| `getFilterOperators(): object[]` | Get the filter operators supported by this field (e.g., `$eq`, `$ne`, etc.) |
+
+## Examples
+
+### Branch rendering based on field type
+
+```ts
+if (!ctx.collectionField) return null;
+const { interface: iface } = ctx.collectionField;
+if (['m2o', 'o2m', 'm2m'].includes(iface)) {
+  // Association field: display associated records
+  const target = ctx.collectionField.targetCollection;
+  // ...
+} else if (iface === 'select' || iface === 'radioGroup') {
+  const options = ctx.collectionField.enum || [];
+  // ...
+}
+```
+
+### Determine if it is an association field and access the target collection
+
+```ts
+if (ctx.collectionField?.isAssociationField()) {
+  const targetCol = ctx.collectionField.targetCollection;
+  const titleField = targetCol?.titleCollectionField?.name;
+  // Process according to the target collection structure
+}
+```
+
+### Get enumeration options
+
+```ts
+const options = ctx.collectionField?.enum ?? [];
+const labels = options.map((o) => (typeof o === 'object' ? o.label : o));
+```
+
+### Conditional rendering based on read-only/view mode
+
+```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)} />);
+}
+```
+
+### Get the title field of the target collection
+
+```ts
+// When displaying an association field, use targetCollectionTitleField to get the title field name
+const titleField = ctx.collectionField?.targetCollectionTitleField;
+const titleKey = titleField?.name ?? 'title';
+const assocValue = ctx.getValue?.() ?? ctx.record?.[ctx.collectionField?.name];
+const label = assocValue?.[titleKey];
+```
+
+## Relationship with ctx.collection
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Current field's collection** | `ctx.collectionField?.collection` or `ctx.collection` |
+| **Field metadata (name, type, interface, enum, etc.)** | `ctx.collectionField` |
+| **Target collection** | `ctx.collectionField?.targetCollection` |
+
+`ctx.collection` usually represents the collection bound to the current block; `ctx.collectionField` represents the definition of the current field in the collection. In scenarios like sub-tables or association fields, the two may differ.
+
+## Notes
+
+- In scenarios such as **JSBlock** or **JSAction (without field binding)**, `ctx.collectionField` is usually `undefined`. It is recommended to use optional chaining before access.
+- If a custom JS field is not bound to a collection field, `ctx.collectionField` may be `null`.
+- `targetCollection` only exists for association type fields (e.g., m2o, o2m, m2m); `enum` only exists for fields with options like select or radioGroup.
+
+## Related
+
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.model](./model.md): Model where the current execution context is located
+- [ctx.blockModel](./block-model.md): Parent block carrying the current JS
+- [ctx.getValue()](./get-value.md), [ctx.setValue()](./set-value.md): Read and write the current field value

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

@@ -0,0 +1,100 @@
+# ctx.collection
+
+The Collection instance associated with the current RunJS execution context, used to access collection metadata, field definitions, primary keys, and other configurations. It usually originates from `ctx.blockModel.collection` or `ctx.collectionField?.collection`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | The collection bound to the block; can access `name`, `getFields`, `filterTargetKey`, etc. |
+| **JSField / JSItem / JSColumn** | The collection the current field belongs to (or the parent block's collection), used to retrieve field lists, primary keys, etc. |
+| **Table Column / Detail Block** | Used for rendering based on collection structure or passing `filterByTk` when opening popups. |
+
+> Note: `ctx.collection` is available in scenarios where a data block, form block, or table block is bound to a collection. In an independent JSBlock that is not bound to a collection, it may be `null`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```ts
+collection: Collection | null | undefined;
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `name` | `string` | Collection name (e.g., `users`, `orders`) |
+| `title` | `string` | Collection title (includes internationalization) |
+| `filterTargetKey` | `string \| string[]` | Primary key field name, used for `filterByTk` and `getFilterByTK` |
+| `dataSourceKey` | `string` | Data source key (e.g., `main`) |
+| `dataSource` | `DataSource` | The data source instance it belongs to |
+| `template` | `string` | Collection template (e.g., `general`, `file`, `tree`) |
+| `titleableFields` | `CollectionField[]` | List of fields that can be displayed as titles |
+| `titleCollectionField` | `CollectionField` | The title field instance |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `getFields(): CollectionField[]` | Get all fields (including inherited ones) |
+| `getField(name: string): CollectionField \| undefined` | Get a single field by field name |
+| `getFieldByPath(path: string): CollectionField \| undefined` | Get a field by path (supports associations, e.g., `user.name`) |
+| `getAssociationFields(types?): CollectionField[]` | Get association fields; `types` can be `['one']`, `['many']`, etc. |
+| `getFilterByTK(record): any` | Extract the primary key value from a record, used for the API's `filterByTk` |
+
+## Relationship with ctx.collectionField and ctx.blockModel
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Collection associated with current context** | `ctx.collection` (equivalent to `ctx.blockModel?.collection` or `ctx.collectionField?.collection`) |
+| **Collection definition of the current field** | `ctx.collectionField?.collection` (the collection the field belongs to) |
+| **Association target collection** | `ctx.collectionField?.targetCollection` (the target collection of an association field) |
+
+In scenarios like sub-tables, `ctx.collection` might be the association target collection; in standard forms/tables, it is usually the collection bound to the block.
+
+## 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 Through 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']) ?? [];
+// Used for building sub-tables, associated resources, etc.
+```
+
+## Notes
+
+- `filterTargetKey` is the primary key field name of the collection. Some collections may use a `string[]` for composite primary keys. If not configured, `'id'` is commonly used as a fallback.
+- In scenarios like **sub-tables or association fields**, `ctx.collection` may point to the association target collection, which differs from `ctx.blockModel.collection`.
+- `getFields()` merges fields from inherited collections; local fields override inherited fields with the same name.
+
+## Related
+
+- [ctx.collectionField](./collection-field.md): The collection field definition of the current field
+- [ctx.blockModel](./block-model.md): The parent block hosting the current JS, containing `collection`
+- [ctx.model](./model.md): The current model, which may contain `collection`

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

@@ -0,0 +1,120 @@
+# ctx.dataSourceManager
+
+The Data Source Manager (`DataSourceManager` instance) is used to manage and access multiple data sources (e.g., the main database `main`, logging database `logging`, etc.). It is used when multiple data sources exist or when cross-data source metadata access is required.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Multi-data source** | Enumerate all data sources, or get a specific data source by key. |
+| **Cross-data source access** | Access metadata using the "data source key + collection name" format when the data source of the current context is unknown. |
+| **Get fields by full path** | Use the `dataSourceKey.collectionName.fieldPath` format to retrieve field definitions across different data sources. |
+
+> Note: If you are only operating on the current data source, prioritize using `ctx.dataSource`. Use `ctx.dataSourceManager` only when you need to enumerate or switch between data sources.
+
+## Type Definition
+
+```ts
+dataSourceManager: DataSourceManager;
+
+class DataSourceManager {
+  constructor();
+
+  // Data source management
+  addDataSource(ds: DataSource | DataSourceOptions): void;
+  upsertDataSource(ds: DataSource | DataSourceOptions): void;
+  removeDataSource(key: string): void;
+  clearDataSources(): void;
+
+  // Read data sources
+  getDataSources(): DataSource[];                     // Get all data sources
+  getDataSource(key: string): DataSource | undefined;  // Get data source by key
+
+  // Access metadata directly by data source + collection
+  getCollection(dataSourceKey: string, collectionName: string): Collection | undefined;
+  getCollectionField(fieldPathWithDataSource: string): CollectionField | undefined;
+}
+```
+
+## Relationship with ctx.dataSource
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to the current context** | `ctx.dataSource` (e.g., the data source of the current page/block) |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **List or switch data sources** | `ctx.dataSourceManager.getDataSources()` / `getDataSource(key)` |
+| **Get collection within the current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within the current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Examples
+
+### Get a Specific Data Source
+
+```ts
+// Get the data source named 'main'
+const mainDS = ctx.dataSourceManager.getDataSource('main');
+
+// Get all collections under this data source
+const collections = mainDS?.getCollections();
+```
+
+### Access Collection Metadata Across Data Sources
+
+```ts
+// Get collection by dataSourceKey + collectionName
+const users = ctx.dataSourceManager.getCollection('main', 'users');
+const orders = ctx.dataSourceManager.getCollection('main', 'orders');
+
+// Get the primary key of the collection
+const primaryKey = users?.filterTargetKey ?? 'id';
+```
+
+### Get Field Definition by Full Path
+
+```ts
+// Format: dataSourceKey.collectionName.fieldPath
+// Get field definition by "data source key.collection name.field path"
+const field = ctx.dataSourceManager.getCollectionField('main.users.profile.avatar');
+
+// Supports association field paths
+const userNameField = ctx.dataSourceManager.getCollectionField('main.orders.createdBy.name');
+```
+
+### Iterate Through All Data Sources
+
+```ts
+const dataSources = ctx.dataSourceManager.getDataSources();
+for (const ds of dataSources) {
+  ctx.logger.info(`Data Source: ${ds.key}, Display Name: ${ds.displayName}`);
+  const collections = ds.getCollections();
+  for (const col of collections) {
+    ctx.logger.info(`  - Collection: ${col.name}`);
+  }
+}
+```
+
+### Dynamically Select Data Source Based on Variables
+
+```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
+
+- The path format for `getCollectionField` is `dataSourceKey.collectionName.fieldPath`, where the first segment is the data source key, followed by the collection name and the field path.
+- `getDataSource(key)` returns `undefined` if the data source does not exist; it is recommended to perform a null check before use.
+- `addDataSource` will throw an exception if the key already exists; `upsertDataSource` will either overwrite the existing one or add a new one.
+
+## Related
+
+- [ctx.dataSource](./data-source.md): Current data source instance
+- [ctx.collection](./collection.md): Collection associated with the current context
+- [ctx.collectionField](./collection-field.md): Collection field definition for the current field

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

@@ -0,0 +1,136 @@
+# ctx.dataSource
+
+The `DataSource` instance bound to the current RunJS execution context, used to access collections, field metadata, and manage collection configurations **within the current data source**. It usually corresponds to the data source selected for the current page or block (e.g., the main database `main`).
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **Single Data Source Operations** | Get collection and field metadata when the current data source is known. |
+| **Collection Management** | Get, add, update, or delete collections under the current data source. |
+| **Get Fields by Path** | Use the `collectionName.fieldPath` format to get field definitions (supports association paths). |
+
+> Note: `ctx.dataSource` represents a single data source for the current context. To enumerate or access other data sources, please use [ctx.dataSourceManager](./data-source-manager.md).
+
+## Type Definition
+
+```ts
+dataSource: DataSource;
+
+class DataSource {
+  constructor(options?: Record<string, any>);
+
+  // Read-only properties
+  get flowEngine(): FlowEngine;   // Current FlowEngine instance
+  get displayName(): string;      // Display name (supports i18n)
+  get key(): string;              // Data source key, e.g., 'main'
+  get name(): string;             // Same as key
+
+  // Collection reading
+  getCollections(): Collection[];                      // Get all collections
+  getCollection(name: string): Collection | undefined; // Get collection by name
+  getAssociation(associationName: string): CollectionField | undefined; // Get association field (e.g., users.roles)
+
+  // Collection management
+  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;
+
+  // Field metadata
+  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 (supports i18n) |
+| `flowEngine` | `FlowEngine` | Current FlowEngine instance |
+
+## Common Methods
+
+| Method | Description |
+|------|------|
+| `getCollections()` | Gets all collections under the current data source (sorted, with hidden ones filtered). |
+| `getCollection(name)` | Gets a collection by name; `name` can be `collectionName.fieldName` to get the target collection of an association. |
+| `getAssociation(associationName)` | Gets an association field definition by `collectionName.fieldName`. |
+| `getCollectionField(fieldPath)` | Gets a field definition by `collectionName.fieldPath`, supporting association paths like `users.profile.avatar`. |
+
+## Relationship with ctx.dataSourceManager
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Single data source bound to current context** | `ctx.dataSource` |
+| **Entry point for all data sources** | `ctx.dataSourceManager` |
+| **Get collection within current data source** | `ctx.dataSource.getCollection(name)` |
+| **Get collection across data sources** | `ctx.dataSourceManager.getCollection(dataSourceKey, collectionName)` |
+| **Get field within current data source** | `ctx.dataSource.getCollectionField('users.profile.avatar')` |
+| **Get field across data sources** | `ctx.dataSourceManager.getCollectionField('main.users.profile.avatar')` |
+
+## Example
+
+### Get Collections and Fields
+
+```ts
+// Get all collections
+const collections = ctx.dataSource.getCollections();
+
+// Get collection by name
+const users = ctx.dataSource.getCollection('users');
+const primaryKey = users?.filterTargetKey ?? 'id';
+
+// Get field definition by "collectionName.fieldPath" (supports associations)
+const field = ctx.dataSource.getCollectionField('users.profile.avatar');
+const userNameField = ctx.dataSource.getCollectionField('orders.createdBy.name');
+```
+
+### Get Association Fields
+
+```ts
+// Get association field definition by collectionName.fieldName
+const rolesField = ctx.dataSource.getAssociation('users.roles');
+if (rolesField?.isAssociationField()) {
+  const targetCol = rolesField.targetCollection;
+  // Process based on target collection structure
+}
+```
+
+### Iterate Through Collections for Dynamic Processing
+
+```ts
+const collections = ctx.dataSource.getCollections();
+for (const col of collections) {
+  const fields = col.getFields();
+  const requiredFields = fields.filter((f) => f.options?.required);
+  // ...
+}
+```
+
+### Perform Validation or Dynamic UI Based on Field Metadata
+
+```ts
+const field = ctx.dataSource.getCollectionField('users.status');
+if (field) {
+  const options = field.enum ?? [];
+  const operators = field.getFilterOperators();
+  // Perform UI logic or validation based on interface, enum, validation, etc.
+}
+```
+
+## Notes
+
+- The path format for `getCollectionField(fieldPath)` is `collectionName.fieldPath`, where the first segment is the collection name and the subsequent segments are the field path (supports associations, e.g., `user.name`).
+- `getCollection(name)` supports the `collectionName.fieldName` format, returning the target collection of the association field.
+- In the RunJS context, `ctx.dataSource` is usually determined by the data source of the current block or page. If no data source is bound to the context, it may be `undefined`; it is recommended to perform a null check before use.
+
+## Related
+
+- [ctx.dataSourceManager](./data-source-manager.md): Data source manager, manages all data sources.
+- [ctx.collection](./collection.md): The collection associated with the current context.
+- [ctx.collectionField](./collection-field.md): The collection field definition for the current field.

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

@@ -0,0 +1,104 @@
+# ctx.element
+
+An `ElementProxy` instance pointing to the sandbox DOM container, serving as the default rendering target for `ctx.render()`. It is available in scenarios where a rendering container exists, such as `JSBlock`, `JSField`, `JSItem`, and `JSColumn`.
+
+## Applicable Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSBlock** | The DOM container for the block, used to render custom block content. |
+| **JSField / JSItem / FormJSFieldItem** | The rendering container for a field or form item (usually a `<span>`). |
+| **JSColumn** | The DOM container for a table cell, used to render custom column content. |
+
+> Note: `ctx.element` is only available in RunJS contexts that have a rendering container. In contexts without a UI (such as pure backend logic), it may be `undefined`. It is recommended to perform a null check before use.
+
+## Type Definition
+
+```typescript
+element: ElementProxy | undefined;
+
+// ElementProxy is a proxy for the raw HTMLElement, exposing a secure API
+class ElementProxy {
+  __el: HTMLElement;  // The internal raw DOM element (accessible only in specific scenarios)
+  innerHTML: string;  // Sanitized via DOMPurify during read/write
+  outerHTML: string; // Same as above
+  appendChild(child: HTMLElement | string): void;
+  // Other HTMLElement methods are passed through (direct use is not recommended)
+}
+```
+
+## Security Requirements
+
+**Recommended: All rendering should be performed via `ctx.render()`.** Avoid using the DOM APIs of `ctx.element` directly (e.g., `innerHTML`, `appendChild`, `querySelector`, etc.).
+
+### Why ctx.render() is Recommended
+
+| Advantage | Description |
+|------|------|
+| **Security** | Centralized security control to prevent XSS and improper DOM operations. |
+| **React Support** | Full support for JSX, React components, and lifecycles. |
+| **Context Inheritance** | Automatically inherits the application's `ConfigProvider`, themes, etc. |
+| **Conflict Handling** | Automatically manages React root creation/unmounting to avoid multi-instance conflicts. |
+
+### ❌ Not Recommended: Direct Manipulation of ctx.element
+
+```ts
+// ❌ Not recommended: Using ctx.element APIs directly
+ctx.element.innerHTML = '<div>Content</div>';
+ctx.element.appendChild(node);
+ctx.element.querySelector('.class');
+```
+
+> `ctx.element.innerHTML` is deprecated. Please use `ctx.render()` instead.
+
+### ✅ Recommended: Using ctx.render()
+
+```ts
+// ✅ Rendering a React component
+const { Button, Card } = ctx.libs.antd;
+ctx.render(
+  <Card title={ctx.t('Welcome')}>
+    <Button type="primary">Click</Button>
+  </Card>
+);
+
+// ✅ Rendering an HTML string
+ctx.render('<div style="padding:16px;">' + ctx.t('Content') + '</div>');
+
+// ✅ Rendering a DOM node
+const div = document.createElement('div');
+div.textContent = ctx.t('Hello');
+ctx.render(div);
+```
+
+## Special Case: As a Popover Anchor
+
+When you need to open a Popover using the current element as an anchor, you can access `ctx.element?.__el` to get the raw DOM as the `target`:
+
+```ts
+// ctx.viewer.popover requires a raw DOM as the target
+await ctx.viewer.popover({
+  target: ctx.element?.__el,
+  content: <div>Popup Content</div>,
+});
+```
+
+> Use `__el` only in scenarios like "using the current container as an anchor"; do not manipulate the DOM directly in other cases.
+
+## Relationship with ctx.render
+
+- If `ctx.render(vnode)` is called without a `container` argument, it renders into the `ctx.element` container by default.
+- If both `ctx.element` is missing and no `container` is provided, an error will be thrown.
+- You can explicitly specify a container: `ctx.render(vnode, customContainer)`.
+
+## Notes
+
+- `ctx.element` is intended for internal use by `ctx.render()`. Directly accessing or modifying its properties/methods is not recommended.
+- In contexts without a rendering container, `ctx.element` will be `undefined`. Ensure the container is available or pass a `container` manually before calling `ctx.render()`.
+- Although `innerHTML`/`outerHTML` in `ElementProxy` are sanitized via DOMPurify, it is still recommended to use `ctx.render()` for unified rendering management.
+
+## Related
+
+- [ctx.render](./render.md): Rendering content into a container
+- [ctx.view](./view.md): Current view controller
+- [ctx.modal](./modal.md): Shortcut API for modals