@nocobase/flow-engine 2.0.0-alpha.7 → 2.0.0-alpha.71

package/src/runjs-context/contexts/JSEditableFieldRunJSContext.ts

@@ -0,0 +1,106 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { FlowRunJSContext } from '../../flowContext';
+
+/**
+ * RunJS context for JSEditableFieldModel (form editable custom field).
+ * NOTE: Some APIs (e.g., getValue/setValue/element) are provided by the model's runtime handler.
+ * This doc is used for editor autocomplete and AI coding assistance.
+ */
+export class JSEditableFieldRunJSContext extends FlowRunJSContext {}
+
+JSEditableFieldRunJSContext.define({
+  label: 'JSEditableField RunJS context',
+  properties: {
+    element: {
+      description:
+        'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
+      detail: 'ElementProxy',
+    },
+    value: {
+      description:
+        'Current field value (read-only snapshot). In editable scenarios, prefer ctx.getValue()/ctx.setValue(v) for two-way binding.',
+      detail: 'any',
+      examples: ['const v = ctx.getValue?.() ?? ctx.value;', 'ctx.setValue?.("new value");'],
+    },
+    record: {
+      description: 'Current record data object (read-only). Available in forms that are bound to a record.',
+      detail: 'Record<string, any>',
+    },
+    form: {
+      description: 'Ant Design Form instance for reading/writing other fields. Example: ctx.form.getFieldValue("name")',
+      detail: 'FormInstance',
+    },
+    formValues: {
+      description:
+        'Snapshot of current form values (object). Prefer ctx.form.getFieldsValue() when you need the latest values.',
+      detail: 'Record<string, any>',
+    },
+    namePath: {
+      description: 'Field namePath in the form (array). Useful for advanced Form operations.',
+      detail: 'Array<string | number>',
+    },
+    disabled: 'Whether the field is disabled (boolean).',
+    readOnly: 'Whether the field is read-only (boolean).',
+  },
+  methods: {
+    getValue: {
+      description: 'Get current field value (recommended for editable custom fields).',
+      detail: '() => any',
+      completion: { insertText: 'ctx.getValue?.()' },
+    },
+    setValue: {
+      description: 'Set current field value (two-way binding with the form).',
+      detail: '(value: any) => void',
+      completion: { insertText: 'ctx.setValue?.(value)' },
+      examples: ['ctx.setValue?.(e.target.value);'],
+    },
+  },
+});
+
+JSEditableFieldRunJSContext.define(
+  {
+    label: 'JS 可编辑字段 RunJS 上下文',
+    properties: {
+      element: {
+        description: 'ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。',
+        detail: 'ElementProxy',
+      },
+      value: {
+        description: '字段当前值（只读快照）。可编辑场景建议使用 ctx.getValue()/ctx.setValue(v) 做双向绑定。',
+        detail: 'any',
+        examples: ['const v = ctx.getValue?.() ?? ctx.value;', 'ctx.setValue?.("新值");'],
+      },
+      record: { description: '当前记录对象（只读；表单绑定记录时可用）。', detail: 'Record<string, any>' },
+      form: { description: 'Ant Design Form 实例，可读写其它字段。', detail: 'FormInstance' },
+      formValues: {
+        description: '当前表单值快照（对象）。需要最新值可用 ctx.form.getFieldsValue()。',
+        detail: 'Record<string, any>',
+      },
+      namePath: { description: '字段在表单中的 namePath（数组）。', detail: 'Array<string | number>' },
+      disabled: '是否禁用（boolean）',
+      readOnly: '是否只读（boolean）',
+    },
+    methods: {
+      getValue: {
+        description: '获取字段当前值（可编辑字段推荐使用）。',
+        detail: '() => any',
+        completion: { insertText: 'ctx.getValue?.()' },
+      },
+      setValue: {
+        description: '设置字段当前值（与表单双向绑定）。',
+        detail: '(value: any) => void',
+        completion: { insertText: 'ctx.setValue?.(value)' },
+        examples: ['ctx.setValue?.(e.target.value);'],
+      },
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSFieldRunJSContext.ts

@@ -7,37 +7,42 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSFieldRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('collection', { get: () => (this as any)._delegate['collection'] });
-  }
-}
+export class JSFieldRunJSContext extends FlowRunJSContext {}
 
 JSFieldRunJSContext.define({
   label: 'JSField RunJS context',
   properties: {
-    element: 'ElementProxy，字段渲染容器',
-    value: '字段当前值（只读）',
-    record: '当前记录（只读）',
-    collection: '集合定义（只读）',
+    element: `ElementProxy instance providing a safe DOM container for field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`,
+    value: `Current value of the field (read-only).
+      Contains the data value stored in this field.`,
+    record: `Current record data object (read-only).
+      Contains all field values of the parent record.`,
+    collection: `Collection definition metadata (read-only).
+      Provides schema information about the collection this field belongs to.`,
   },
   methods: {
-    onRefReady: 'Container ready callback',
-  },
-  snipastes: {
-    'Render value': { $ref: 'scene/jsfield/innerHTML-value', prefix: 'sn-jsf-value' },
-    'Message success': { $ref: 'global/message-success', prefix: 'sn-msg-ok' },
-    'Format number': { $ref: 'scene/jsfield/format-number', prefix: 'sn-jsf-num' },
-    'Color by value': { $ref: 'scene/jsfield/color-by-value', prefix: 'sn-jsf-color' },
+    onRefReady: `Wait for field container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void
+      Example: ctx.onRefReady(ctx.ref, (el) => { el.innerHTML = ctx.value })`,
   },
 });
+
+JSFieldRunJSContext.define(
+  {
+    label: 'JS 字段 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作',
+      value: '字段当前值（只读）',
+      record: '当前记录对象（只读，包含父记录全部字段值）',
+      collection: '集合定义元数据（只读，描述字段所属集合的 Schema）',
+    },
+    methods: {
+      onRefReady:
+        '在字段容器 DOM 就绪后执行回调。参数：(ref, callback, timeout?)；示例：ctx.onRefReady(ctx.ref, el => { el.innerHTML = ctx.value })',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -7,33 +7,47 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSItemRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
-  }
-}
+export class JSItemRunJSContext extends FlowRunJSContext {}
 
 JSItemRunJSContext.define({
   label: 'JSItem RunJS context',
   properties: {
-    element: 'ElementProxy，表单项渲染容器',
-    resource: '当前资源（只读）',
-    record: '当前记录（只读）',
+    element: `ElementProxy instance providing a safe DOM container for form item rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`,
+    resource: `Current resource instance (read-only).
+      Provides access to the data resource associated with the current form context.`,
+    record: `Current record data object (read-only).
+      Contains all field values of the parent record.`,
+    formValues: {
+      description: 'Snapshot of current form values (object). Available in form contexts (CreateForm/EditForm).',
+      detail: 'Record<string, any>',
+      examples: ['const { name, status } = ctx.formValues || {};'],
+    },
   },
   methods: {
-    onRefReady: 'Container ready callback',
-    requireAsync: 'Load external library',
-  },
-  snipastes: {
-    'Render form item': { $ref: 'scene/jsitem/render-basic', prefix: 'sn-jsitem-basic' },
+    onRefReady: `Wait for form item container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void`,
   },
 });
+
+JSItemRunJSContext.define(
+  {
+    label: 'JS 表单项 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作',
+      resource: '当前资源（只读）',
+      record: '当前记录（只读）',
+      formValues: {
+        description: '当前表单值快照（对象）。仅表单相关上下文可用（Create/Edit Form）。',
+        detail: 'Record<string, any>',
+        examples: ['const { name, status } = ctx.formValues || {};'],
+      },
+    },
+    methods: {
+      onRefReady: '容器就绪后执行回调。参数：(ref, callback, timeout?)',
+    },
+  },
+  { locale: 'zh-CN' },
+);

package/src/runjs-context/contexts/JSRecordActionRunJSContext.ts

@@ -7,28 +7,27 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSRecordActionRunJSContext extends FlowRunJSContext {
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('filterByTk', { get: () => (this as any)._delegate['filterByTk'] });
-  }
-}
+export class JSRecordActionRunJSContext extends FlowRunJSContext {}
 
 JSRecordActionRunJSContext.define({
   label: 'JSRecordAction RunJS context',
   properties: {
-    record: '当前记录（只读）',
-    filterByTk: '主键/过滤键（只读）',
-  },
-  methods: {
-    runAction: 'Run action: `await ctx.runAction(name, params)`',
-    message: 'Message API',
-  },
-  snipastes: {
-    'Show record id': { $ref: 'scene/actions/record-id-message', prefix: 'sn-act-record-id' },
-    'Run action': { $ref: 'scene/actions/run-action-basic', prefix: 'sn-act-run' },
+    record: `Current record data object (read-only).
+      Contains all field values of the record associated with this action.`,
+    filterByTk: `Primary key or filter key of the current record (read-only).
+      Used to identify the specific record in database operations.`,
   },
 });
+
+JSRecordActionRunJSContext.define(
+  {
+    label: 'JS 记录动作 RunJS 上下文',
+    properties: {
+      record: '当前记录（只读）',
+      filterByTk: '主键/过滤键（只读）',
+    },
+  },
+  { locale: 'zh-CN' },
+);