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

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

@@ -0,0 +1,84 @@
+# ctx.logger
+
+Logging built on [pino](https://github.com/pinojs/pino); outputs structured JSON. Prefer `ctx.logger` over `console` for collection and analysis.
+
+## Use Cases
+
+Available in all RunJS contexts for debugging, error tracking, and performance.
+
+## Type
+
+```ts
+logger: pino.Logger;
+```
+
+`ctx.logger` is `engine.logger.child({ module: 'flow-engine' })`, i.e. a pino child logger with a `module` context.
+
+## Log levels
+
+From highest to lowest:
+
+| Level | Method | Description |
+|-------|--------|-------------|
+| `fatal` | `ctx.logger.fatal()` | Fatal; usually process exit |
+| `error` | `ctx.logger.error()` | Error; request or operation failed |
+| `warn` | `ctx.logger.warn()` | Warning; potential issue |
+| `info` | `ctx.logger.info()` | General runtime info |
+| `debug` | `ctx.logger.debug()` | Debug; development |
+| `trace` | `ctx.logger.trace()` | Verbose; deep diagnosis |
+
+## Recommended usage
+
+Use `level(msg, meta)`: message first, optional metadata object second.
+
+```ts
+ctx.logger.info('Block loaded');
+ctx.logger.info('Success', { recordId: 456 });
+ctx.logger.warn('Slow', { duration: 5000 });
+ctx.logger.error('Failed', { userId: 123, action: 'create' });
+ctx.logger.error('Request failed', { err });
+```
+
+pino also supports `level(meta, msg)` or `level({ msg, ...meta })` if needed.
+
+## Examples
+
+### Basic
+
+```ts
+ctx.logger.info('Block loaded');
+ctx.logger.warn('Request failed, using cache', { err });
+ctx.logger.debug('Saving', { recordId: ctx.record?.id });
+```
+
+### Child logger
+
+```ts
+const log = ctx.logger.child({ scope: 'myBlock' });
+log.info('Step 1');
+log.debug('Step 2', { step: 2 });
+```
+
+### vs console
+
+Prefer `ctx.logger` for structured JSON. Rough mapping: `console.log` → `ctx.logger.info`, `console.error` → `ctx.logger.error`, `console.warn` → `ctx.logger.warn`.
+
+## Output format
+
+pino outputs JSON with:
+
+- `level`: numeric level
+- `time`: timestamp (ms)
+- `msg`: message
+- `module`: `flow-engine`
+- Any custom fields passed in the object
+
+## Notes
+
+- Logs are JSON for easy collection and querying
+- Child loggers from `child()` also work well with `level(msg, meta)`
+- Some environments (e.g. workflow) may use different log handling
+
+## Related
+
+- [pino](https://github.com/pinojs/pino)

package/dist/ai/docs/runjs/context/make-resource.md

@@ -0,0 +1,89 @@
+# ctx.makeResource()
+
+**Creates** a new resource instance and returns it; **does not** set or change `ctx.resource`. Use when you need multiple resources or a temporary one.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **Multiple resources** | Load several data sources (e.g. users + orders), each with its own resource |
+| **One-off query** | Single query, no need to bind to `ctx.resource` |
+| **Auxiliary data** | Main data in `ctx.resource`, extra data from a `makeResource` instance |
+
+If you only need one resource and want it on `ctx.resource`, use [ctx.initResource()](./init-resource.md).
+
+## Type
+
+```ts
+makeResource<T = FlowResource>(
+  resourceType: 'APIResource' | 'SingleRecordResource' | 'MultiRecordResource' | 'SQLResource'
+): T;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resourceType` | `string` | `'APIResource'`, `'SingleRecordResource'`, `'MultiRecordResource'`, `'SQLResource'` |
+
+**Returns**: The new resource instance.
+
+## Relation to ctx.initResource()
+
+| Method | Behavior |
+|--------|----------|
+| `ctx.makeResource(type)` | Creates and returns; **does not** set `ctx.resource`; can call multiple times for multiple resources |
+| `ctx.initResource(type)` | Creates and binds if missing; otherwise returns existing. Ensures `ctx.resource` is set |
+
+## Examples
+
+### Single resource
+
+```ts
+const listRes = ctx.makeResource('MultiRecordResource');
+listRes.setResourceName('users');
+await listRes.refresh();
+const users = listRes.getData();
+// ctx.resource unchanged (if it existed)
+```
+
+### Multiple resources
+
+```ts
+const usersRes = ctx.makeResource('MultiRecordResource');
+usersRes.setResourceName('users');
+await usersRes.refresh();
+
+const ordersRes = ctx.makeResource('MultiRecordResource');
+ordersRes.setResourceName('orders');
+await ordersRes.refresh();
+
+ctx.render(
+  <div>
+    <p>Users: {usersRes.getData().length}</p>
+    <p>Orders: {ordersRes.getData().length}</p>
+  </div>
+);
+```
+
+### One-off query
+
+```ts
+const tempRes = ctx.makeResource('SingleRecordResource');
+tempRes.setResourceName('users');
+tempRes.setFilterByTk(1);
+await tempRes.refresh();
+const record = tempRes.getData();
+```
+
+## Notes
+
+- Call `setResourceName(name)` then `refresh()` to load data.
+- Each instance is independent; good for loading several sources in parallel.
+
+## Related
+
+- [ctx.initResource()](./init-resource.md): init and bind to `ctx.resource`
+- [ctx.resource](./resource.md): current context resource
+- [MultiRecordResource](../resource/multi-record-resource.md)
+- [SingleRecordResource](../resource/single-record-resource.md)
+- [APIResource](../resource/api-resource.md)
+- [SQLResource](../resource/sql-resource.md)

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

@@ -0,0 +1,106 @@
+# ctx.message
+
+Ant Design global message API; shows short messages at the top center. Messages auto-close after a while or can be closed by the user.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField / JSItem / JSColumn** | Quick feedback: validation, copy success, etc. |
+| **Form actions / event flow** | Submit success, save failed, validation failed |
+| **JSAction** | Click or batch action feedback |
+
+## Type
+
+```ts
+message: MessageInstance;
+```
+
+`MessageInstance` is the Ant Design message API.
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `success(content, duration?)` | Success message |
+| `error(content, duration?)` | Error message |
+| `warning(content, duration?)` | Warning message |
+| `info(content, duration?)` | Info message |
+| `loading(content, duration?)` | Loading (usually closed manually) |
+| `open(config)` | Open with custom config |
+| `destroy()` | Close all messages |
+
+**Parameters:**
+
+- `content`: `string` or `ConfigOptions`
+- `duration`: optional seconds; default 3; 0 = no auto-close
+
+**ConfigOptions** (when content is an object):
+
+```ts
+interface ConfigOptions {
+  content: React.ReactNode;
+  duration?: number;
+  onClose?: () => void;
+  icon?: React.ReactNode;
+}
+```
+
+## Examples
+
+### Basic
+
+```ts
+ctx.message.success('Done');
+ctx.message.error('Failed');
+ctx.message.warning('Please select data first');
+ctx.message.info('Processing...');
+```
+
+### With ctx.t (i18n)
+
+```ts
+ctx.message.success(ctx.t('Copied'));
+ctx.message.warning(ctx.t('Please select at least one row'));
+ctx.message.success(ctx.t('Exported {{count}} records', { count: rows.length }));
+```
+
+### Loading and manual close
+
+```ts
+const hide = ctx.message.loading(ctx.t('Saving...'));
+await saveData();
+hide();
+ctx.message.success(ctx.t('Saved'));
+```
+
+### open with config
+
+```ts
+ctx.message.open({
+  type: 'success',
+  content: 'Custom success',
+  duration: 5,
+  onClose: () => console.log('closed'),
+});
+```
+
+### Close all
+
+```ts
+ctx.message.destroy();
+```
+
+## ctx.message vs ctx.notification
+
+| | ctx.message | ctx.notification |
+|---|-------------|-------------------|
+| **Position** | Top center | Top right |
+| **Use** | Short, auto-dismiss | Panel with title/description; can stay longer |
+| **Typical** | Action feedback, validation, copy | Task done, system notice, longer content |
+
+## Related
+
+- [ctx.notification](./notification.md): top-right notifications
+- [ctx.modal](./modal.md): modal confirm
+- [ctx.t()](./t.md): i18n; often used with message

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

@@ -0,0 +1,115 @@
+# ctx.modal
+
+Shortcut API built on Ant Design Modal for opening modals (info, confirm, etc.) from RunJS. Implemented by `ctx.viewer` / the view system.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / JSField** | Show result, error, or confirmation after user action |
+| **Event flow / action events** | Confirm before submit; use `ctx.exit()` when user cancels |
+| **Linkage** | Show modal when validation fails |
+
+> Note: `ctx.modal` is available in RunJS when a view context exists (e.g. JSBlock on a page, event flow); in backend or no-UI contexts it may be absent—use optional chaining: `ctx.modal?.confirm?.()`.
+
+## Type
+
+```ts
+modal: {
+  info: (config: ModalConfig) => Promise<void>;
+  success: (config: ModalConfig) => Promise<void>;
+  error: (config: ModalConfig) => Promise<void>;
+  warning: (config: ModalConfig) => Promise<void>;
+  confirm: (config: ModalConfig) => Promise<boolean>;  // true = OK, false = Cancel
+};
+```
+
+`ModalConfig` matches Ant Design Modal static method config.
+
+## Common Methods
+
+| Method | Returns | Description |
+|--------|--------|-------------|
+| `info(config)` | `Promise<void>` | Info modal |
+| `success(config)` | `Promise<void>` | Success modal |
+| `error(config)` | `Promise<void>` | Error modal |
+| `warning(config)` | `Promise<void>` | Warning modal |
+| `confirm(config)` | `Promise<boolean>` | Confirm; OK → `true`, Cancel → `false` |
+
+## Config
+
+Same as Ant Design `Modal`; common fields:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `title` | `ReactNode` | Title |
+| `content` | `ReactNode` | Content |
+| `okText` | `string` | OK button text |
+| `cancelText` | `string` | Cancel button text (`confirm` only) |
+| `onOk` | `() => void \| Promise<void>` | On OK click |
+| `onCancel` | `() => void` | On Cancel click |
+
+## Relation to ctx.message, ctx.openView
+
+| Use | Recommended |
+|-----|-------------|
+| **Short auto-dismiss** | `ctx.message` |
+| **Info/success/error/warning modal** | `ctx.modal.info` / `success` / `error` / `warning` |
+| **Confirm (user choice)** | `ctx.modal.confirm`; use `ctx.exit()` to control flow |
+| **Complex form, list, etc.** | `ctx.openView` for custom view (page/drawer/dialog) |
+
+## Examples
+
+### Simple info
+
+```ts
+ctx.modal.info({
+  title: 'Notice',
+  content: 'Operation completed',
+});
+```
+
+### Confirm and control flow
+
+```ts
+const confirmed = await ctx.modal.confirm({
+  title: 'Confirm delete',
+  content: 'Delete this record?',
+  okText: 'OK',
+  cancelText: 'Cancel',
+});
+if (!confirmed) {
+  ctx.exit();
+  return;
+}
+await ctx.runAction('destroy', { filterByTk: ctx.record?.id });
+```
+
+### Confirm with onOk
+
+```ts
+await ctx.modal.confirm({
+  title: 'Confirm submit',
+  content: 'Cannot be changed after submit. Continue?',
+  async onOk() {
+    await ctx.form.submit();
+  },
+});
+```
+
+### Error
+
+```ts
+try {
+  await someOperation();
+  ctx.modal.success({ title: 'Success', content: 'Done' });
+} catch (e) {
+  ctx.modal.error({ title: 'Error', content: e.message });
+}
+```
+
+## Related
+
+- [ctx.message](./message.md): short auto-dismiss messages
+- [ctx.exit()](./exit.md): when user cancels confirm, use `if (!confirmed) ctx.exit()`
+- [ctx.openView()](./open-view.md): open custom view for complex flows

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

@@ -0,0 +1,82 @@
+# ctx.model
+
+The `FlowModel` instance for the current RunJS execution context; the default entry in JSBlock, JSField, JSAction, etc. The concrete type varies: e.g. `BlockModel`, `ActionModel`, `JSEditableFieldModel`.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock** | `ctx.model` is the block model; access `resource`, `collection`, `setProps`, etc. |
+| **JSField / JSItem / JSColumn** | `ctx.model` is the field model; access `setProps`, `dispatchEvent`, etc. |
+| **Action events / ActionModel** | `ctx.model` is the action model; read/write step params, dispatch events, etc. |
+
+> Tip: For the **parent block** that hosts the current JS (e.g. form/table block), use `ctx.blockModel`; for **other models** use `ctx.getModel(uid)`.
+
+## Type
+
+```ts
+model: FlowModel;
+```
+
+`FlowModel` is the base; at runtime it is a subclass (e.g. `BlockModel`, `FormBlockModel`, `TableBlockModel`, `JSEditableFieldModel`, `ActionModel`). Properties and methods depend on the type.
+
+## Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `uid` | `string` | Model unique id; use with `ctx.getModel(uid)` or popup binding |
+| `collection` | `Collection` | Collection bound to the model (when block/field is bound to data) |
+| `resource` | `Resource` | Resource instance; refresh, get selected rows, etc. |
+| `props` | `object` | UI/behavior config; update with `setProps` |
+| `subModels` | `Record<string, FlowModel>` | Child models (e.g. form fields, table columns) |
+| `parent` | `FlowModel` | Parent model (if any) |
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `setProps(partialProps: any): void` | Update model config and trigger re-render (e.g. `ctx.model.setProps({ loading: true })`) |
+| `dispatchEvent(eventName: string, payload?: any, options?: any): Promise<any[]>` | Dispatch event to the model; runs flows listening for that event. Optional `payload` to handler; `options.debounce` for debounce |
+| `getStepParams?.(flowKey, stepKey)` | Read flow step params (settings panel, custom actions, etc.) |
+| `setStepParams?.(flowKey, stepKey, params)` | Write flow step params |
+
+## Relation to ctx.blockModel, ctx.getModel
+
+| Need | Recommended |
+|------|-------------|
+| **Model for current execution context** | `ctx.model` |
+| **Parent block of current JS** | `ctx.blockModel`; use for `resource`, `form`, `collection` |
+| **Any model by uid** | `ctx.getModel(uid)` or `ctx.getModel(uid, true)` (cross view stack) |
+
+In JSField, `ctx.model` is the field model and `ctx.blockModel` is the form/table block that hosts it.
+
+## Examples
+
+### Update block/action state
+
+```ts
+ctx.model.setProps({ loading: true });
+await doSomething();
+ctx.model.setProps({ loading: false });
+```
+
+### Dispatch model event
+
+```ts
+await ctx.model.dispatchEvent('remove');
+
+await ctx.model.dispatchEvent('customEvent', { id: 123 });
+```
+
+### Use uid for popup or cross-model
+
+```ts
+const myUid = ctx.model.uid;
+const other = ctx.getModel('other-block-uid');
+if (other) other.rerender?.();
+```
+
+## Related
+
+- [ctx.blockModel](./block-model.md): parent block of current JS
+- [ctx.getModel()](./get-model.md): get another model by uid

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

@@ -0,0 +1,105 @@
+# ctx.notification
+
+Global notification API based on Ant Design Notification; shows notifications in the **top-right**. Compared to `ctx.message`, notifications can have title and description and stay longer.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **JSBlock / action events** | Task done, batch result, export done |
+| **Event flow** | System notice after async flow ends |
+| **Longer content** | Full notification with title, description, actions |
+
+## Type
+
+```ts
+notification: NotificationInstance;
+```
+
+`NotificationInstance` is the Ant Design notification API.
+
+## Common Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(config)` | Open with custom config |
+| `success(config)` | Success notification |
+| `info(config)` | Info notification |
+| `warning(config)` | Warning notification |
+| `error(config)` | Error notification |
+| `destroy(key?)` | Close notification by key; no key = close all |
+
+**Config** (same as [Ant Design notification](https://ant.design/components/notification)):
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | `ReactNode` | Title |
+| `description` | `ReactNode` | Description |
+| `duration` | `number` | Auto-close seconds; default 4.5; 0 = no auto-close |
+| `key` | `string` | Unique id for `destroy(key)` |
+| `onClose` | `() => void` | On close |
+| `placement` | `string` | `topLeft` \| `topRight` \| `bottomLeft` \| `bottomRight` |
+
+## Examples
+
+### Basic
+
+```ts
+ctx.notification.open({
+  message: 'Success',
+  description: 'Data saved.',
+});
+```
+
+### By type
+
+```ts
+ctx.notification.success({
+  message: ctx.t('Export completed'),
+  description: ctx.t('Exported {{count}} records', { count: 10 }),
+});
+
+ctx.notification.error({
+  message: ctx.t('Export failed'),
+  description: ctx.t('Check console for details'),
+});
+
+ctx.notification.warning({
+  message: ctx.t('Warning'),
+  description: ctx.t('Some data may be incomplete'),
+});
+```
+
+### Custom duration and key
+
+```ts
+ctx.notification.open({
+  key: 'task-123',
+  message: ctx.t('Task in progress'),
+  description: ctx.t('Please wait...'),
+  duration: 0,
+});
+
+ctx.notification.destroy('task-123');
+```
+
+### Close all
+
+```ts
+ctx.notification.destroy();
+```
+
+## ctx.message vs ctx.notification
+
+| | ctx.message | ctx.notification |
+|---|-------------|-------------------|
+| **Position** | Top center | Top right (configurable) |
+| **Structure** | Single line | Title + description |
+| **Use** | Short, auto-dismiss | Longer, can stay |
+| **Typical** | Success, validation, copy | Task done, system notice |
+
+## Related
+
+- [ctx.message](./message.md): top-center short messages
+- [ctx.modal](./modal.md): modal confirm
+- [ctx.t()](./t.md): i18n; often used with notification

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

@@ -0,0 +1,48 @@
+# ctx.off()
+
+Removes a listener registered with `ctx.on(eventName, handler)`. Use with [ctx.on](./on.md) and unsubscribe when appropriate to avoid leaks or duplicate triggers.
+
+## Use Cases
+
+| Scenario | Description |
+|----------|-------------|
+| **React useEffect cleanup** | Call in `useEffect` cleanup; remove on unmount |
+| **JSField / JSEditableField** | Unsubscribe from `js-field:value-change` when doing two-way binding |
+| **resource** | Unsubscribe from `ctx.resource.on` (refresh, saved, etc.) |
+
+## Type
+
+```ts
+off(eventName: string, handler: (event?: any) => void): void;
+```
+
+## Examples
+
+### Pair with on in useEffect
+
+```tsx
+React.useEffect(() => {
+  const handler = (ev) => setValue(ev?.detail ?? '');
+  ctx.on('js-field:value-change', handler);
+  return () => ctx.off('js-field:value-change', handler);
+}, []);
+```
+
+### Unsubscribe resource event
+
+```ts
+const handler = () => { /* ... */ };
+ctx.resource?.on('refresh', handler);
+// Later
+ctx.resource?.off('refresh', handler);
+```
+
+## Notes
+
+1. **Same handler reference**: The `handler` passed to `ctx.off` must be the same reference as in `ctx.on`, or it will not be removed.
+2. **Clean up in time**: Call `ctx.off` before unmount or context destroy to avoid leaks.
+
+## Related
+
+- [ctx.on](./on.md): subscribe to events
+- [ctx.resource](./resource.md): resource and its `on`/`off`