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

package/dist/ai/docs/runjs/context/exit-all.md

@@ -0,0 +1,94 @@
+# ctx.exitAll()
+
+Stops the current event flow and all **subsequent** event flows that were triggered in the same event dispatch. Use when a global error or permission check requires stopping every flow for that event.
+
+## Use Cases
+
+Use `ctx.exitAll()` in JS-capable contexts when you need to **stop both the current flow and any later flows for the same event**:
+
+| Scenario | Description |
+|----------|-------------|
+| **Event flow** | Main flow fails (e.g. no permission); stop it and any subsequent flows for that event |
+| **Linkage rules** | When linkage validation fails and you want to stop current and subsequent linkage |
+| **Action events** | Pre-action check fails (e.g. delete permission); block the action and later steps |
+
+> Difference from `ctx.exit()`: `ctx.exit()` only stops the current flow; `ctx.exitAll()` also stops **subsequent** flows for that event.
+
+## Type
+
+```ts
+exitAll(): never;
+```
+
+Calling `ctx.exitAll()` throws an internal `FlowExitAllException`, which the engine uses to stop the current flow instance and subsequent flows for the same event. The rest of the current JS does not run.
+
+## Comparison with ctx.exit()
+
+| Method | Scope |
+|--------|--------|
+| `ctx.exit()` | Stops only the current flow; later flows still run |
+| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+
+## Execution mode
+
+- **Sequential**: flows for the same event run one after another; after any flow calls `ctx.exitAll()`, later flows do not run.
+- **Parallel**: flows run in parallel; one flow calling `ctx.exitAll()` does not stop other already-running flows.
+
+## Examples
+
+### Stop all flows on permission failure
+
+```ts
+if (!hasPermission(ctx)) {
+  ctx.notification.error({ message: 'No permission' });
+  ctx.exitAll();
+}
+```
+
+### Stop on global pre-check failure
+
+```ts
+const canDelete = await checkDeletable(ctx.model?.getValue?.());
+if (!canDelete) {
+  ctx.message.error('Cannot delete: related data exists');
+  ctx.exitAll();
+}
+```
+
+### When to use ctx.exit() vs ctx.exitAll()
+
+```ts
+// Only this flow → ctx.exit()
+if (!params.valid) {
+  ctx.message.error('Invalid params');
+  ctx.exit();
+}
+
+// This and all subsequent flows → ctx.exitAll()
+if (!ctx.model?.context?.getPermission?.()) {
+  ctx.notification.warning({ message: 'No permission' });
+  ctx.exitAll();
+}
+```
+
+### Message then exit
+
+```ts
+if (!isValidInput(ctx.form?.getValues?.())) {
+  ctx.message.warning('Please fix form errors first');
+  ctx.exitAll();
+}
+```
+
+## Notes
+
+- After `ctx.exitAll()`, the rest of the current JS does not run; explain to the user with `ctx.message`, `ctx.notification`, or a dialog before calling.
+- You usually do not need to catch `FlowExitAllException`; the engine handles it.
+- To stop only the current flow, use `ctx.exit()`.
+- In parallel mode, `ctx.exitAll()` only stops the current flow; it does not cancel other concurrent flows.
+
+## Related
+
+- [ctx.exit()](./exit.md): stop only the current flow
+- [ctx.message](./message.md): message API
+- [ctx.modal](./modal.md): confirm dialog

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

@@ -0,0 +1,101 @@
+# ctx.exit()
+
+Stops the current event flow; later steps in that flow do not run. Often used when business conditions fail, the user cancels, or an unrecoverable error occurs.
+
+## Use Cases
+
+`ctx.exit()` is used in contexts that execute JS, such as:
+
+| Scenario | Description |
+|----------|-------------|
+| **Event flow** | In flows triggered by form submit, button click, etc., stop when conditions are not met |
+| **Linkage rules** | Field or filter linkage; stop when validation fails or execution should be skipped |
+| **Action events** | In custom actions (e.g. delete confirm, pre-save validation), exit when user cancels or validation fails |
+
+> Difference from `ctx.exitAll()`: `ctx.exit()` only stops the **current** event flow; other flows for the same event still run. `ctx.exitAll()` also stops **subsequent** flows for that event.
+
+## Type
+
+```ts
+exit(): never;
+```
+
+Calling `ctx.exit()` throws an internal `FlowExitException`, which the event flow engine catches and uses to stop the current flow. Once called, the rest of the current JS does not run.
+
+## Comparison with ctx.exitAll()
+
+| Method | Scope |
+|--------|--------|
+| `ctx.exit()` | Stops only the current event flow; others unaffected |
+| `ctx.exitAll()` | Stops the current flow and **subsequent** flows for the same event |
+
+## Examples
+
+### Exit on user cancel
+
+```ts
+if (!confirmed) {
+  ctx.message.info('Cancelled');
+  ctx.exit();
+}
+```
+
+### Exit on validation failure
+
+```ts
+if (!params.value || params.value.length < 3) {
+  ctx.message.error('Invalid: length must be at least 3');
+  ctx.exit();
+}
+```
+
+### Exit when business condition fails
+
+```ts
+const record = ctx.model?.getValue?.();
+if (!record || record.status !== 'draft') {
+  ctx.notification.warning({ message: 'Only draft can be submitted' });
+  ctx.exit();
+}
+```
+
+### When to use ctx.exit() vs ctx.exitAll()
+
+```ts
+// Only this flow should stop → ctx.exit()
+if (!params.valid) {
+  ctx.message.error('Invalid params');
+  ctx.exit();
+}
+
+// Stop this and all subsequent flows for this event → ctx.exitAll()
+if (!ctx.model?.context?.getPermission?.()) {
+  ctx.notification.warning({ message: 'No permission' });
+  ctx.exitAll();
+}
+```
+
+### Exit after modal confirm
+
+```ts
+const ok = await ctx.modal?.confirm?.({
+  title: 'Confirm delete',
+  content: 'Cannot be recovered. Continue?',
+});
+if (!ok) {
+  ctx.message.info('Cancelled');
+  ctx.exit();
+}
+```
+
+## Notes
+
+- After `ctx.exit()`, the rest of the current JS does not run; use `ctx.message`, `ctx.notification`, or a dialog before calling to explain why.
+- You usually do not need to catch `FlowExitException`; the event flow engine handles it.
+- To stop all subsequent flows for the same event, use `ctx.exitAll()`.
+
+## Related
+
+- [ctx.exitAll()](./exit-all.md): stop current and subsequent flows for the event
+- [ctx.message](./message.md): message API
+- [ctx.modal](./modal.md): confirm dialog

package/dist/ai/docs/runjs/context/filter-manager.md

@@ -0,0 +1,96 @@
+# ctx.filterManager
+
+The filter connection manager that links filter forms (FilterForm) to data blocks (tables, lists, charts, etc.). Provided by `BlockGridModel`; only available in that context (e.g. pages with a filter form block).
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Filter form block** | Manage connections between filter items and target blocks; refresh targets when filters change |
+| **Data block (table/list)** | Act as filter target; bind filter conditions via `bindToTarget` |
+| **Linkage / custom FilterModel** | In `doFilter`, `doReset`, call `refreshTargetsByFilter` to refresh targets |
+| **Connection field config** | Use `getConnectFieldsConfig`, `saveConnectFieldsConfig` for filter–target field mapping |
+
+> Note: `ctx.filterManager` is only available in RunJS contexts that have a `BlockGridModel` (e.g. pages with a filter form); in a plain JSBlock or standalone page it is `undefined`—check before use.
+
+## Type
+
+```ts
+filterManager: FilterManager;
+
+type FilterConfig = {
+  filterId: string;
+  targetId: string;
+  filterPaths?: string[];
+  operator?: string;
+};
+
+type ConnectFieldsConfig = {
+  targets: { targetId: string; filterPaths: string[] }[];
+};
+```
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `getFilterConfigs()` | All filter connection configs |
+| `getConnectFieldsConfig(filterId)` | Connection field config for a filter |
+| `saveConnectFieldsConfig(filterId, config)` | Save connection field config for a filter |
+| `addFilterConfig(config)` | Add filter config (filterId + targetId + filterPaths) |
+| `removeFilterConfig({ filterId?, targetId?, persist? })` | Remove config by filterId and/or targetId |
+| `bindToTarget(targetId)` | Bind filter to target block; its resource applies the filter |
+| `unbindFromTarget(targetId)` | Unbind filter from target |
+| `refreshTargetsByFilter(filterId or filterId[])` | Refresh target block(s) by filter |
+
+## Concepts
+
+- **FilterModel**: Provides filter values (e.g. FilterFormItemModel); must implement `getFilterValue()`.
+- **TargetModel**: Data block being filtered; its `resource` must support `addFilterGroup`, `removeFilterGroup`, `refresh`.
+
+## Examples
+
+### Add filter config
+
+```ts
+await ctx.filterManager?.addFilterConfig({
+  filterId: 'filter-form-item-uid',
+  targetId: 'table-block-uid',
+  filterPaths: ['status', 'createdAt'],
+  operator: '$eq',
+});
+```
+
+### Refresh target blocks
+
+```ts
+ctx.filterManager?.refreshTargetsByFilter(ctx.model.uid);
+
+ctx.filterManager?.refreshTargetsByFilter(['filter-1', 'filter-2']);
+```
+
+### Connection field config
+
+```ts
+const config = ctx.filterManager?.getConnectFieldsConfig(ctx.model.uid);
+
+await ctx.filterManager?.saveConnectFieldsConfig(ctx.model.uid, {
+  targets: [
+    { targetId: 'table-uid', filterPaths: ['status'] },
+    { targetId: 'chart-uid', filterPaths: ['category'] },
+  ],
+});
+```
+
+### Remove config
+
+```ts
+await ctx.filterManager?.removeFilterConfig({ filterId: 'filter-uid' });
+
+await ctx.filterManager?.removeFilterConfig({ targetId: 'table-uid' });
+```
+
+## Related
+
+- [ctx.resource](./resource.md): target block’s resource must support filter APIs
+- [ctx.model](./model.md): current model uid for filterId / targetId

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

@@ -0,0 +1,169 @@
+# ctx.form
+
+The Ant Design Form instance for the current block; used to read/write form fields, trigger validation, and submit. Same as `ctx.blockModel?.form`; in form blocks (Form, EditForm, sub-forms, etc.) you can use it directly.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField** | Read/write other fields for linkage, compute or validate from other field values |
+| **JSItem** | Read/write same row or other fields in sub-table items |
+| **JSColumn** | Read row or related field values for column rendering |
+| **Form actions / event flow** | Pre-submit validation, batch field updates, reset form, etc. |
+
+> Note: `ctx.form` is only available in RunJS contexts tied to a form block (Form, EditForm, sub-forms, etc.); in non-form contexts (e.g. standalone JSBlock, table block) it may be absent—check before use: `ctx.form?.getFieldsValue()`.
+
+## Type
+
+```ts
+form: FormInstance<any>;
+```
+
+`FormInstance` is the Ant Design Form instance type.
+
+## Common Methods
+
+### Read form values
+
+```ts
+// Current registered field values (default: only rendered fields)
+const values = ctx.form.getFieldsValue();
+
+// All field values (including unrendered, e.g. hidden, collapsed)
+const allValues = ctx.form.getFieldsValue(true);
+
+// Single field
+const email = ctx.form.getFieldValue('email');
+
+// Nested (e.g. sub-table)
+const amount = ctx.form.getFieldValue(['orders', 0, 'amount']);
+```
+
+### Write form values
+
+```ts
+// Batch update (e.g. linkage)
+ctx.form.setFieldsValue({
+  status: 'active',
+  updatedAt: new Date(),
+});
+
+// Single field
+ctx.form.setFieldValue('remark', 'Noted');
+```
+
+### Validation and submit
+
+```ts
+// Trigger validation
+await ctx.form.validateFields();
+
+// Trigger submit
+ctx.form.submit();
+```
+
+### Reset
+
+```ts
+// All fields
+ctx.form.resetFields();
+
+// Specific fields
+ctx.form.resetFields(['status', 'remark']);
+```
+
+## Relation to Other Context
+
+### ctx.getValue / ctx.setValue
+
+| Scenario | Recommended |
+|----------|-------------|
+| **Current field** | `ctx.getValue()` / `ctx.setValue(v)` |
+| **Other fields** | `ctx.form.getFieldValue(name)` / `ctx.form.setFieldValue(name, v)` |
+
+In the current JS field, use `getValue`/`setValue` for that field; use `ctx.form` for other fields.
+
+### ctx.blockModel
+
+| Need | Recommended |
+|------|-------------|
+| **Read/write form fields** | `ctx.form` (same as `ctx.blockModel?.form`) |
+| **Parent block** | `ctx.blockModel` (includes `collection`, `resource`, etc.) |
+
+### ctx.getVar('ctx.formValues')
+
+Form values are obtained via `await ctx.getVar('ctx.formValues')`, not as `ctx.formValues`. In form contexts, prefer `ctx.form.getFieldsValue()` for up-to-date values.
+
+## Notes
+
+- `getFieldsValue()` by default returns only rendered fields; for unrendered (e.g. collapsed) use `getFieldsValue(true)`.
+- Nested paths use arrays, e.g. `['orders', 0, 'amount']`; you can use `ctx.namePath` to build paths for other columns in the same row.
+- `validateFields()` throws with `errorFields` etc. on failure; use `ctx.exit()` to stop further steps when validation fails.
+- In event flow or linkage, `ctx.form` may not be ready yet; use optional chaining or null checks.
+
+## Examples
+
+### Field linkage by type
+
+```ts
+const type = ctx.form.getFieldValue('type');
+if (type === 'vip') {
+  ctx.form.setFieldsValue({ discount: 0.8 });
+} else {
+  ctx.form.setFieldsValue({ discount: 1 });
+}
+```
+
+### Compute current field from others
+
+```ts
+const quantity = ctx.form.getFieldValue('quantity') ?? 0;
+const price = ctx.form.getFieldValue('price') ?? 0;
+ctx.setValue(quantity * price);
+```
+
+### Same row in sub-table
+
+```ts
+// ctx.namePath is current field path, e.g. ['orders', 0, 'amount']
+// Same row status: ['orders', 0, 'status']
+const rowIndex = ctx.namePath?.[1];
+const status = ctx.form.getFieldValue(['orders', rowIndex, 'status']);
+```
+
+### Pre-submit validation
+
+```ts
+try {
+  await ctx.form.validateFields();
+  // Continue submit logic
+} catch (e) {
+  ctx.message.error('Please fix form errors');
+  ctx.exit();
+}
+```
+
+### Confirm then submit
+
+```ts
+const confirmed = await ctx.modal.confirm({
+  title: 'Confirm submit',
+  content: 'Cannot be changed after submit. Continue?',
+  okText: 'OK',
+  cancelText: 'Cancel',
+});
+if (confirmed) {
+  await ctx.form.validateFields();
+  ctx.form.submit();
+} else {
+  ctx.exit();
+}
+```
+
+## Related
+
+- [ctx.getValue()](./get-value.md) / [ctx.setValue()](./set-value.md): read/write current field
+- [ctx.blockModel](./block-model.md): parent block; `ctx.form` is `ctx.blockModel?.form`
+- [ctx.modal](./modal.md): confirm dialog, often with `ctx.form.validateFields()` / `ctx.form.submit()`
+- [ctx.exit()](./exit.md): stop flow on validation failure or cancel
+- `ctx.namePath`: current field path in the form (array); use for nested `getFieldValue` / `setFieldValue` names

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

@@ -0,0 +1,84 @@
+# ctx.getModel()
+
+Returns a model instance (e.g. BlockModel, PageModel, ActionModel) from the current engine or view stack by its `uid`. Use in RunJS to access other models across blocks, pages, or popups.
+
+If you only need the model or block for the current execution context, use `ctx.model` or `ctx.blockModel` instead of `ctx.getModel`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSAction** | Get another block’s model by known `uid`; read/write its `resource`, `form`, `setProps`, etc. |
+| **RunJS inside popup** | Access a model on the page that opened the popup; pass `searchInPreviousEngines: true` |
+| **Custom actions** | Find a form or sub-model in the settings panel across the view stack by `uid` |
+
+## Type
+
+```ts
+getModel<T extends FlowModel = FlowModel>(
+  uid: string,
+  searchInPreviousEngines?: boolean
+): T | undefined
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uid` | `string` | Unique id of the target model (e.g. from config or creation) |
+| `searchInPreviousEngines` | `boolean` | Optional, default `false`. When `true`, search up the view stack from the current engine to find models in parent views (e.g. the page that opened the popup) |
+
+## Return value
+
+- Returns the corresponding `FlowModel` subclass (e.g. `BlockModel`, `FormBlockModel`, `ActionModel`) if found.
+- Returns `undefined` if not found.
+
+## Search scope
+
+- **Default (`searchInPreviousEngines: false`)**: Search only in the **current engine** by `uid`. In popups or nested views, each view has its own engine; by default only the current view is searched.
+- **`searchInPreviousEngines: true`**: Search from the current engine along the `previousEngine` chain; returns the first match. Use when RunJS in a popup needs to access a model on the page that opened it.
+
+## Examples
+
+### Get another block and refresh
+
+```ts
+const block = ctx.getModel('list-block-uid');
+if (block?.resource) {
+  await block.resource.refresh();
+}
+```
+
+### Access page model from inside popup
+
+```ts
+const pageBlock = ctx.getModel('page-block-uid', true);
+if (pageBlock) {
+  pageBlock.rerender?.();
+}
+```
+
+### Cross-model update and rerender
+
+```ts
+const target = ctx.getModel('other-block-uid');
+if (target) {
+  target.setProps({ loading: true });
+  target.rerender?.();
+}
+```
+
+### Null check
+
+```ts
+const model = ctx.getModel(someUid);
+if (!model) {
+  ctx.message.warning('Target model not found');
+  return;
+}
+```
+
+## Related
+
+- [ctx.model](./model.md): model for current execution context
+- [ctx.blockModel](./block-model.md): parent block of current JS; often no need for `getModel`

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

@@ -0,0 +1,64 @@
+# ctx.getValue()
+
+In JSField, JSItem, and other editable field contexts, returns the current value of the field. Use with `ctx.setValue(v)` for two-way binding with the form.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSField** | Read user input or current form value in editable custom fields |
+| **JSItem** | Read current cell value in table/sub-table editable items |
+| **JSColumn** | Read row field value when rendering a column |
+
+> Note: `ctx.getValue()` is only available in RunJS contexts with form binding; it does not exist in event flow, linkage, etc., where there is no field binding.
+
+## Type
+
+```ts
+getValue<T = any>(): T | undefined;
+```
+
+- **Returns**: Current field value; type depends on the field’s form item type. May be `undefined` if the field is not registered or not filled.
+
+## Value resolution
+
+`ctx.getValue()` resolves in this order:
+
+1. **Form state**: Prefer current Ant Design Form state.
+2. **Fallback**: If the field is not in the form, use the field’s initial value or props.
+
+If the form is not yet rendered or the field is not registered, the result may be `undefined`.
+
+## Examples
+
+### Render based on current value
+
+```ts
+const current = ctx.getValue();
+if (current == null || current === '') {
+  ctx.render(<span>Please enter something</span>);
+} else {
+  ctx.render(<span>Current: {current}</span>);
+}
+```
+
+### Two-way binding with setValue
+
+```tsx
+const { Input } = ctx.libs.antd;
+
+const defaultValue = ctx.getValue() ?? '';
+
+ctx.render(
+  <Input
+    defaultValue={defaultValue}
+    onChange={(e) => ctx.setValue(e.target.value)}
+  />
+);
+```
+
+## Related
+
+- [ctx.setValue()](./set-value.md): set current field value; use with getValue for two-way binding
+- [ctx.form](./form.md): Ant Design Form instance for other fields
+- `js-field:value-change`: container event when value changes from outside; use to update display