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

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

@@ -1,97 +1,94 @@
 # 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.
+**Asynchronously** reads a variable from the current runtime context. Variable sources are the same as for SQL and template `{{ctx.xxx}}`: current user, current record, view params, 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}}`. |
+|----------|-------------|
+| **JSBlock / JSField** | Get current record, user, resource, etc. for rendering or logic |
+| **Linkage / event flow** | Read `ctx.record`, `ctx.formValues`, etc. for conditions |
+| **Formulas / templates** | Same variable resolution as `{{ctx.xxx}}` |
 
-## Type Definition
+## Type
 
 ```ts
 getVar(path: string): Promise<any>;
 ```
 
 | Parameter | Type | Description |
-|------|------|------|
-| `path` | `string` | Variable path; **must start with `ctx.`**. Supports dot notation and array indices. |
+|-----------|------|-------------|
+| `path` | `string` | Variable path; **must start with `ctx.`**; supports dot and array index |
 
-**Return Value**: `Promise<any>`. Use `await` to get the resolved value; returns `undefined` if the variable does not exist.
+**Returns**: `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: "..."`.
+> If the path does not start with `ctx.`, an error is thrown: `ctx.getVar(path) expects an expression starting with "ctx.", got: "..."`.
 
-## Common Variable Paths
+## Common paths
 
 | Path | Description |
-|------|------|
-| `ctx.record` | Current record (available when a form/details block is bound to a record) |
+|------|-------------|
+| `ctx.record` | Current record (when form/detail 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.formValues` | Current form values (common in linkage/event flow; in form context prefer `ctx.form.getFieldsValue()` for live values) |
+| `ctx.user` | Current 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.popup.record` | Record in popup |
+| `ctx.popup.record.id` | Popup record primary key |
+| `ctx.urlSearchParams` | URL query params (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.
+Returns **structure info** (type, title, child properties, etc.) for variables that can be resolved in the current context. Useful to discover available paths. Values are static meta, not runtime values.
 
-### Type Definition
+### Type
 
 ```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.).
+Each key in the result is a variable path; each value is that path’s structure (e.g. `type`, `title`, `properties`).
 
-### Parameters
+### Options
 
-| 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`. |
+| Option | Type | Description |
+|--------|------|-------------|
+| `path` | `string \| string[]` | Limit to paths under this; e.g. `'record'`, `'record.id'`, `'ctx.record'`, `'{{ ctx.record }}'`; array = multiple paths merged |
+| `maxDepth` | `number` | Max depth to expand; default `3`. Without path, top-level depth=1; with path, that node 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
+## Relation to 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.`. |
+| Method | Context | Description |
+|--------|---------|-------------|
+| `ctx.getValue()` | JSField, JSItem, etc. | Sync; **current field** value; requires form binding |
+| `ctx.getVar(path)` | Any RunJS | Async; **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`).
+In JSField, use getValue/setValue for the field; use getVar for other context (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.
+- **Path must start with `ctx.`**: e.g. `ctx.record.id`; otherwise an error is thrown.
+- **Async**: Use `await`, e.g. `const id = await ctx.getVar('ctx.record.id')`.
+- **Missing variable**: Returns `undefined`; use `??` for default: `(await ctx.getVar('ctx.user.nickname')) ?? 'Guest'`.
+- **Form values**: Get via `await ctx.getVar('ctx.formValues')`; not exposed as `ctx.formValues`. In form context prefer `ctx.form.getFieldsValue()` for latest values.
 
 ## Examples
 
-### Get Current Record ID
+### Current record id
 
 ```ts
 const recordId = await ctx.getVar('ctx.record.id');
@@ -100,58 +97,55 @@ if (recordId) {
 }
 ```
 
-### Get Record Within a Popup
+### Popup record
 
 ```ts
 const recordId = await ctx.getVar('ctx.popup.record.id');
 if (recordId) {
-  ctx.message.info(`Current popup record: ${recordId}`);
+  ctx.message.info(`Popup record: ${recordId}`);
 }
 ```
 
-### Read Sub-items of an Array Field
+### Array field items
 
 ```ts
 const roleNames = await ctx.getVar('ctx.user.roles.name');
-// Returns an array of role names, e.g., ['admin', 'member']
+// e.g. ['admin', 'member']
 ```
 
-### Set Default Value
+### 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
+### Form field value
 
 ```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
+### URL query params
 
 ```ts
-const id = await ctx.getVar('ctx.urlSearchParams.id'); // Corresponds to ?id=xxx
+const id = await ctx.getVar('ctx.urlSearchParams.id'); // ?id=xxx
 ```
 
-### Explore Available Variables
+### Explore 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' }, ... }
+// e.g. { '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')`
+- [ctx.getValue()](./get-value.md): sync current field value (JSField/JSItem only)
+- [ctx.form](./form.md): form instance; `ctx.form.getFieldsValue()` for live form values
+- [ctx.model](./model.md): current model
+- [ctx.blockModel](./block-model.md): parent block
+- [ctx.resource](./resource.md): resource in current context
+- SQL / template `{{ctx.xxx}}`: same resolution as `ctx.getVar('ctx.xxx')`

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

@@ -1,12 +1,12 @@
 # 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`.
+The i18n instance for the current context; used to read or change the language. **Use [ctx.t()](./t.md) for all translated text**; do not use `ctx.i18n.t`.
 
-## Scenarios
+## Use Cases
 
-All RunJS execution environments can use `ctx.i18n` (e.g., JSBlock, JSField, JSItem, JSColumn, Workflow, Linkage Rules, etc.).
+Available in all RunJS environments (JSBlock, JSField, JSItem, JSColumn, event flow, linkage, etc.).
 
-## Type Definition
+## Type
 
 ```typescript
 interface i18n: {
@@ -18,28 +18,27 @@ interface i18n: {
 ## Common Properties
 
 | Property | Type | Description |
-|------|------|------|
-| `language` | `string` | The currently active language code (e.g., `en-US`, `zh-CN`) |
+|----------|------|-------------|
+| `language` | `string` | Current language code (e.g. `zh-CN`, `en-US`) |
 
 ## Common Methods
 
 ### changeLanguage(lng)
 
-Switches the current language.
+Change the current language.
 
 | Parameter | Type | Description |
-|------|------|------|
-| `lng` | `string` | Target language code (e.g., `'en-US'`, `'zh-CN'`) |
+|-----------|------|-------------|
+| `lng` | `string` | Target language code (e.g. `en-US`, `zh-CN`) |
 
-**Returns**: `Promise<any>`, resolves after the language switch is complete.
+**Returns**: `Promise<any>`, resolves when the language has been changed.
 
 ## Examples
 
-### Reading the current language
+### Read current language
 
 ```ts
 const lang = ctx.i18n.language;
-// 'en-US' | 'zh-CN' | ...
 if (lang.startsWith('zh')) {
   ctx.render(ctx.t('Chinese UI'));
 } else {
@@ -47,13 +46,11 @@ if (lang.startsWith('zh')) {
 }
 ```
 
-### Switching languages
+### Change language
 
 ```ts
-// Switch to English
 await ctx.i18n.changeLanguage('en-US');
 
-// Switch to Chinese
 await ctx.i18n.changeLanguage('zh-CN');
 ```
 
@@ -73,8 +70,8 @@ ctx.render(
 
 ## Notes
 
-- **Translation text**: Use `ctx.t()` consistently; do not use `ctx.i18n.t`.
+- **Translated text**: Use `ctx.t()` only; do not use `ctx.i18n.t`.
 
 ## Related
 
-- [ctx.t()](./t.md): Translate text, use this method consistently.
+- [ctx.t()](./t.md): translation; use this for all copy