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

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

@@ -0,0 +1,169 @@
+# ctx.form
+
+The Ant Design Form instance within the current block, used to read/write form fields, trigger validation, and submission. It is equivalent to `ctx.blockModel?.form` and can be used directly in form-related blocks (Form, Edit Form, Sub-form, etc.).
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Read/write other form fields to implement linkage, or perform calculations and validation based on other field values. |
+| **JSItem** | Read/write same-row or other fields within sub-table items to achieve in-table linkage. |
+| **JSColumn** | Read the current row or association field values in a table column for rendering. |
+| **Form Actions / Workflow** | Pre-submission validation, batch updating fields, resetting forms, etc. |
+
+> Note: `ctx.form` is only available in RunJS contexts related to form blocks (Form, Edit Form, Sub-form, etc.). It may not exist in non-form scenarios (such as independent JSBlocks or Table blocks). It is recommended to perform a null check before use: `ctx.form?.getFieldsValue()`.
+
+## Type Definition
+
+```ts
+form: FormInstance<any>;
+```
+
+`FormInstance` is the instance type of Ant Design Form. Common methods are as follows.
+
+## Common Methods
+
+### Reading Form Values
+
+```ts
+// Read values of currently registered fields (defaults to rendered fields only)
+const values = ctx.form.getFieldsValue();
+
+// Read values of all fields (including registered but unrendered fields, e.g., hidden or inside collapsed sections)
+const allValues = ctx.form.getFieldsValue(true);
+
+// Read a single field
+const email = ctx.form.getFieldValue('email');
+
+// Read nested fields (e.g., in a sub-table)
+const amount = ctx.form.getFieldValue(['orders', 0, 'amount']);
+```
+
+### Writing Form Values
+
+```ts
+// Batch update (commonly used for linkage)
+ctx.form.setFieldsValue({
+  status: 'active',
+  updatedAt: new Date(),
+});
+
+// Update a single field
+ctx.form.setFieldValue('remark', 'Updated remark');
+```
+
+### Validation and Submission
+
+```ts
+// Trigger form validation
+await ctx.form.validateFields();
+
+// Trigger form submission
+ctx.form.submit();
+```
+
+### Resetting
+
+```ts
+// Reset all fields
+ctx.form.resetFields();
+
+// Reset only specific fields
+ctx.form.resetFields(['status', 'remark']);
+```
+
+## Relationship with Related Contexts
+
+### ctx.getValue / ctx.setValue
+
+| Scenario | Recommended Usage |
+|------|----------|
+| **Read/Write current field** | `ctx.getValue()` / `ctx.setValue(v)` |
+| **Read/Write other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
+
+Within the current JS field, prioritize using `getValue`/`setValue` to read/write the field itself; use `ctx.form` when you need to access other fields.
+
+### ctx.blockModel
+
+| Requirement | Recommended Usage |
+|------|----------|
+| **Read/Write form fields** | `ctx.form` (Equivalent to `ctx.blockModel?.form`, more convenient) |
+| **Access parent block** | `ctx.blockModel` (Contains `collection`, `resource`, etc.) |
+
+### ctx.getVar('ctx.formValues')
+
+Form values must be obtained via `await ctx.getVar('ctx.formValues')` and are not directly exposed as `ctx.formValues`. In a form context, it is preferred to use `ctx.form.getFieldsValue()` to read the latest values in real-time.
+
+## Notes
+
+- `getFieldsValue()` returns only rendered fields by default. To include unrendered fields (e.g., in collapsed sections or hidden by conditional rules), pass `true`: `getFieldsValue(true)`.
+- Paths for nested fields like sub-tables are arrays, e.g., `['orders', 0, 'amount']`. You can use `ctx.namePath` to get the current field's path and construct paths for other columns in the same row.
+- `validateFields()` throws an error object containing `errorFields` and other information. If validation fails before submission, you can use `ctx.exit()` to terminate subsequent steps.
+- In asynchronous scenarios like workflows or linkage rules, `ctx.form` might not be ready yet. It is recommended to use optional chaining or null checks.
+
+## Examples
+
+### Field Linkage: Display different content based on type
+
+```ts
+const type = ctx.form.getFieldValue('type');
+if (type === 'vip') {
+  ctx.form.setFieldsValue({ discount: 0.8 });
+} else {
+  ctx.form.setFieldsValue({ discount: 1 });
+}
+```
+
+### Calculate current field based on other fields
+
+```ts
+const quantity = ctx.form.getFieldValue('quantity') ?? 0;
+const price = ctx.form.getFieldValue('price') ?? 0;
+ctx.setValue(quantity * price);
+```
+
+### Read/Write other columns in the same row within a sub-table
+
+```ts
+// ctx.namePath is the path of the current field in the form, e.g., ['orders', 0, 'amount']
+// Read 'status' in the same row: ['orders', 0, 'status']
+const rowIndex = ctx.namePath?.[1];
+const status = ctx.form.getFieldValue(['orders', rowIndex, 'status']);
+```
+
+### Pre-submission Validation
+
+```ts
+try {
+  await ctx.form.validateFields();
+  // Validation passed, continue with submission logic
+} catch (e) {
+  ctx.message.error('Please check the form fields');
+  ctx.exit();
+}
+```
+
+### Submit after Confirmation
+
+```ts
+const confirmed = await ctx.modal.confirm({
+  title: 'Confirm Submission',
+  content: 'You will not be able to modify this after submission. Continue?',
+  okText: 'Confirm',
+  cancelText: 'Cancel',
+});
+if (confirmed) {
+  await ctx.form.validateFields();
+  ctx.form.submit();
+} else {
+  ctx.exit(); // Terminate if user cancels
+}
+```
+
+## Related
+
+- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): Read and write the current field value.
+- [ctx.blockModel](./block-model.md): Parent block model; `ctx.form` is equivalent to `ctx.blockModel?.form`.
+- [ctx.modal](./modal.md): Confirmation dialogs, often used with `ctx.form.validateFields()` and `ctx.form.submit()`.
+- [ctx.exit()](./exit.md): Terminate the process upon validation failure or user cancellation.
+- `ctx.namePath`: The path (array) of the current field in the form, used to construct names for `getFieldValue` / `setFieldValue` in nested fields.

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

@@ -0,0 +1,85 @@
+# ctx.getModel()
+
+Retrieves a model instance (such as `BlockModel`, `PageModel`, `ActionModel`, etc.) from the current engine or view stack based on the model `uid`. This is used in RunJS to access other models across blocks, pages, or popups.
+
+If you only need the model or block where the current execution context is located, prioritize using `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSAction** | Get models of other blocks based on a known `uid` to read or write their `resource`, `form`, `setProps`, etc. |
+| **RunJS in Popups** | When needing to access a model on the page that opened the popup, pass `searchInPreviousEngines: true`. |
+| **Custom Actions** | Locate forms or sub-models in the configuration panel by `uid` across view stacks to read their configuration or state. |
+
+## Type Definition
+
+```ts
+getModel<T extends FlowModel = FlowModel>(
+  uid: string,
+  searchInPreviousEngines?: boolean
+): T | undefined
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `uid` | `string` | The unique identifier of the target model instance, specified during configuration or creation (e.g., `ctx.model.uid`). |
+| `searchInPreviousEngines` | `boolean` | Optional, defaults to `false`. When `true`, searches from the current engine up to the root in the "view stack," allowing access to models in upper-level engines (e.g., the page that opened a popup). |
+
+## Return Value
+
+- Returns the corresponding `FlowModel` subclass instance (e.g., `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
+- Returns `undefined` if not found.
+
+## Search Scope
+
+- **Default (`searchInPreviousEngines: false`)**: Searches only within the **current engine** by `uid`. In popups or multi-level views, each view has an independent engine; by default, it only searches for models within the current view.
+- **`searchInPreviousEngines: true`**: Searches upwards along the `previousEngine` chain starting from the current engine, returning the first match. This is useful for accessing a model on the page that opened the current popup.
+
+## Examples
+
+### Get another block and refresh
+
+```ts
+const block = ctx.getModel('list-block-uid');
+if (block?.resource) {
+  await block.resource.refresh();
+}
+```
+
+### Access a model on the page from a popup
+
+```ts
+// Access a block on the page that opened the current popup
+const pageBlock = ctx.getModel('page-block-uid', true);
+if (pageBlock) {
+  pageBlock.rerender?.();
+}
+```
+
+### Cross-model read/write and trigger rerender
+
+```ts
+const target = ctx.getModel('other-block-uid');
+if (target) {
+  target.setProps({ loading: true });
+  target.rerender?.();
+}
+```
+
+### Safety check
+
+```ts
+const model = ctx.getModel(someUid);
+if (!model) {
+  ctx.message.warning('Target model does not exist');
+  return;
+}
+```
+
+## Related
+
+- [ctx.model](./model.md): The model where the current execution context is located.
+- [ctx.blockModel](./block-model.md): The parent block model where the current JS is located; usually accessible without needing `getModel`.

package/dist/ai/docs/runjs/context/get-value.md

@@ -0,0 +1,65 @@
+# ctx.getValue()
+
+In editable field scenarios such as JSField and JSItem, use this to get the latest value of the current field. Combined with `ctx.setValue(v)`, it enables two-way binding with the form.
+
+## Scenarios
+
+| Scenario | Description |
+|------|------|
+| **JSField** | Read user input or the current form value in editable custom fields. |
+| **JSItem** | Read the current cell value in editable items of tables/sub-tables. |
+| **JSColumn** | Read the field value of the corresponding row during table column rendering. |
+
+> **Note**: `ctx.getValue()` is only available in RunJS contexts with form binding; it does not exist in scenarios without field binding, such as workflows or linkage rules.
+
+## Type Definition
+
+```ts
+getValue<T = any>(): T | undefined;
+```
+
+- **Return Value**: The current field value, whose type is determined by the field's form item type; it may be `undefined` if the field is not registered or not filled.
+
+## Retrieval Order
+
+`ctx.getValue()` retrieves values in the following order:
+
+1. **Form State**: Prioritizes reading from the current state of the Ant Design Form.
+2. **Fallback Value**: If the field is not in the form, it falls back to the field's initial value or props.
+
+> If the form has not finished rendering or the field is not registered, it may return `undefined`.
+
+## Examples
+
+### Render based on current value
+
+```ts
+const current = ctx.getValue();
+if (current == null || current === '') {
+  ctx.render(<span>Please enter content first</span>);
+} else {
+  ctx.render(<span>Current value: {current}</span>);
+}
+```
+
+### Two-way binding with setValue
+
+```tsx
+const { Input } = ctx.libs.antd;
+
+// Read current value as default value
+const defaultValue = ctx.getValue() ?? '';
+
+ctx.render(
+  <Input
+    defaultValue={defaultValue}
+    onChange={(e) => ctx.setValue(e.target.value)}
+  />
+);
+```
+
+## Related
+
+- [ctx.setValue()](./set-value.md) - Set the current field value, used with `getValue` for two-way binding.
+- [ctx.form](./form.md) - Ant Design Form instance, for reading/writing other fields.
+- `js-field:value-change` - Container event triggered when external values change, used to update the display.

package/dist/ai/docs/runjs/context/get-var.md

@@ -0,0 +1,157 @@
+# ctx.getVar()
+
+Asynchronously reads variable values from the current runtime context. Variable resolution is consistent with `{{ctx.xxx}}` in SQL and templates, typically originating from the current user, current record, view parameters, popup context, etc.
+
+## Use Cases
+
+| Scenario | Description |
+|------|------|
+| **JSBlock / JSField** | Get information about the current record, user, resource, etc., for rendering or logic. |
+| **Linkage Rules / FlowEngine** | Read `ctx.record`, `ctx.formValues`, etc., for conditional logic. |
+| **Formulas / Templates** | Uses the same variable resolution rules as `{{ctx.xxx}}`. |
+
+## Type Definition
+
+```ts
+getVar(path: string): Promise<any>;
+```
+
+| Parameter | Type | Description |
+|------|------|------|
+| `path` | `string` | Variable path; **must start with `ctx.`**. Supports dot notation and array indices. |
+
+**Return Value**: `Promise<any>`. Use `await` to get the resolved value; returns `undefined` if the variable does not exist.
+
+> If a path that does not start with `ctx.` is passed, an error will be thrown: `ctx.getVar(path) expects an expression starting with "ctx.", got: "..."`.
+
+## Common Variable Paths
+
+| Path | Description |
+|------|------|
+| `ctx.record` | Current record (available when a form/details block is bound to a record) |
+| `ctx.record.id` | Current record primary key |
+| `ctx.formValues` | Current form values (commonly used in linkage rules and FlowEngine; in form scenarios, prefer `ctx.form.getFieldsValue()` for real-time reading) |
+| `ctx.user` | Current logged-in user |
+| `ctx.user.id` | Current user ID |
+| `ctx.user.nickname` | Current user nickname |
+| `ctx.user.roles.name` | Current user role names (array) |
+| `ctx.popup.record` | Record within a popup |
+| `ctx.popup.record.id` | Primary key of the record within a popup |
+| `ctx.urlSearchParams` | URL query parameters (parsed from `?key=value`) |
+| `ctx.token` | Current API Token |
+| `ctx.role` | Current role |
+
+## ctx.getVarInfos()
+
+Gets the **structural information** (type, title, sub-properties, etc.) of resolvable variables in the current context, making it easier to explore available paths. The return value is a static description based on `meta` and does not include actual runtime values.
+
+### Type Definition
+
+```ts
+getVarInfos(options?: { path?: string | string[]; maxDepth?: number }): Promise<Record<string, any>>;
+```
+
+In the return value, each key is a variable path, and the value is the structural information for that path (including `type`, `title`, `properties`, etc.).
+
+### Parameters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `path` | `string \| string[]` | Truncation path; only collects the variable structure under this path. Supports `'record'`, `'record.id'`, `'ctx.record'`, `'{{ ctx.record }}'`; an array represents the merging of multiple paths. |
+| `maxDepth` | `number` | Maximum expansion depth, default is `3`. When `path` is not provided, top-level properties have `depth=1`. When `path` is provided, the node corresponding to the path has `depth=1`. |
+
+### Example
+
+```ts
+// Get the variable structure under record (expanded up to 3 levels)
+const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
+
+// Get the structure of popup.record
+const vars = await ctx.getVarInfos({ path: 'popup.record', maxDepth: 3 });
+
+// Get the complete top-level variable structure (default maxDepth=3)
+const vars = await ctx.getVarInfos();
+```
+
+## Difference from ctx.getValue
+
+| Method | Scenario | Description |
+|------|----------|------|
+| `ctx.getValue()` | Editable fields like JSField or JSItem | Synchronously gets the value of the **current field**; requires form binding. |
+| `ctx.getVar(path)` | Any RunJS context | Asynchronously gets **any ctx variable**; path must start with `ctx.`. |
+
+In a JSField, use `getValue`/`setValue` to read/write the current field; use `getVar` to access other context variables (such as `record`, `user`, `formValues`).
+
+## Notes
+
+- **Path must start with `ctx.`**: e.g., `ctx.record.id`, otherwise an error will be thrown.
+- **Asynchronous method**: You must use `await` to get the result, e.g., `const id = await ctx.getVar('ctx.record.id')`.
+- **Variable does not exist**: Returns `undefined`. You can use `??` after the result to set a default value: `(await ctx.getVar('ctx.user.nickname')) ?? 'Guest'`.
+- **Form values**: `ctx.formValues` must be retrieved via `await ctx.getVar('ctx.formValues')`; it is not directly exposed as `ctx.formValues`. In a form context, prefer using `ctx.form.getFieldsValue()` to read the latest values in real-time.
+
+## Examples
+
+### Get Current Record ID
+
+```ts
+const recordId = await ctx.getVar('ctx.record.id');
+if (recordId) {
+  ctx.message.info(`Current record: ${recordId}`);
+}
+```
+
+### Get Record Within a Popup
+
+```ts
+const recordId = await ctx.getVar('ctx.popup.record.id');
+if (recordId) {
+  ctx.message.info(`Current popup record: ${recordId}`);
+}
+```
+
+### Read Sub-items of an Array Field
+
+```ts
+const roleNames = await ctx.getVar('ctx.user.roles.name');
+// Returns an array of role names, e.g., ['admin', 'member']
+```
+
+### Set Default Value
+
+```ts
+// getVar does not have a defaultValue parameter; use ?? after the result
+const userName = (await ctx.getVar('ctx.user.nickname')) ?? 'Guest';
+```
+
+### Read Form Field Values
+
+```ts
+// Both ctx.formValues and ctx.form are for form scenarios; use getVar to read nested fields
+const status = await ctx.getVar('ctx.formValues.status');
+if (status === 'draft') {
+  // ...
+}
+```
+
+### Read URL Query Parameters
+
+```ts
+const id = await ctx.getVar('ctx.urlSearchParams.id'); // Corresponds to ?id=xxx
+```
+
+### Explore Available Variables
+
+```ts
+// Get the variable structure under record (expanded up to 3 levels)
+const vars = await ctx.getVarInfos({ path: 'record', maxDepth: 3 });
+// vars looks like { 'record.id': { type: 'string', title: 'id' }, ... }
+```
+
+## Related
+
+- [ctx.getValue()](./get-value.md) - Synchronously gets the current field value (JSField/JSItem only)
+- [ctx.form](./form.md) - Form instance; `ctx.form.getFieldsValue()` can read form values in real-time
+- [ctx.model](./model.md) - The model where the current execution context resides
+- [ctx.blockModel](./block-model.md) - The parent block where the current JS is located
+- [ctx.resource](./resource.md) - The resource instance in the current context
+- `{{ctx.xxx}}` in SQL / Templates - Uses the same resolution rules as `ctx.getVar('ctx.xxx')`

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

@@ -0,0 +1,80 @@
+# ctx.i18n
+
+The i18n instance of the current context, used for reading or switching languages. **Use [ctx.t()](./t.md) for translating text**; do not use `ctx.i18n.t`.
+
+## Scenarios
+
+All RunJS execution environments can use `ctx.i18n` (e.g., JSBlock, JSField, JSItem, JSColumn, Workflow, Linkage Rules, etc.).
+
+## Type Definition
+
+```typescript
+interface i18n: {
+  language: string;
+  changeLanguage(lng: string): Promise<any>;
+}
+```
+
+## Common Properties
+
+| Property | Type | Description |
+|------|------|------|
+| `language` | `string` | The currently active language code (e.g., `en-US`, `zh-CN`) |
+
+## Common Methods
+
+### changeLanguage(lng)
+
+Switches the current language.
+
+| Parameter | Type | Description |
+|------|------|------|
+| `lng` | `string` | Target language code (e.g., `'en-US'`, `'zh-CN'`) |
+
+**Returns**: `Promise<any>`, resolves after the language switch is complete.
+
+## Examples
+
+### Reading the current language
+
+```ts
+const lang = ctx.i18n.language;
+// 'en-US' | 'zh-CN' | ...
+if (lang.startsWith('zh')) {
+  ctx.render(ctx.t('Chinese UI'));
+} else {
+  ctx.render(ctx.t('English UI'));
+}
+```
+
+### Switching languages
+
+```ts
+// Switch to English
+await ctx.i18n.changeLanguage('en-US');
+
+// Switch to Chinese
+await ctx.i18n.changeLanguage('zh-CN');
+```
+
+### Language switch button
+
+```ts
+const { Button } = ctx.libs.antd;
+const isZh = ctx.i18n.language.startsWith('zh');
+ctx.render(
+  <Button onClick={async () => {
+    await ctx.i18n.changeLanguage(isZh ? 'en-US' : 'zh-CN');
+  }}>
+    {ctx.t(isZh ? 'Switch to English' : 'Switch to Chinese')}
+  </Button>,
+);
+```
+
+## Notes
+
+- **Translation text**: Use `ctx.t()` consistently; do not use `ctx.i18n.t`.
+
+## Related
+
+- [ctx.t()](./t.md): Translate text, use this method consistently.