@nocobase/flow-engine 2.0.0-alpha.4 → 2.0.0-alpha.41

package/src/runjs-context/snippets/global/clipboard-copy-text.snippet.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { SnippetModule } from '../types';
+
+const snippet: SnippetModule = {
+  contexts: ['*'],
+  prefix: 'sn-clipboard-copy',
+  label: 'Copy text to clipboard (function)',
+  description: 'A reusable function that copies a given string to the clipboard.',
+  locales: {
+    'zh-CN': {
+      label: '复制文本到剪贴板（函数）',
+      description: '通用函数：接受一个字符串参数并复制到剪贴板。',
+    },
+  },
+  content: `
+// A general utility function that copies text to clipboard.
+// Usage:
+//   const ok = await copyTextToClipboard('Hello');
+//   if (ok) { /* success */ } else { /* handle failure */ }
+async function copyTextToClipboard(text) {
+  const s = String(text ?? '');
+  try {
+    if (navigator?.clipboard?.writeText) {
+      await navigator.clipboard.writeText(s);
+      return true;
+    }
+  } catch (_) {
+    // Fallback below
+  }
+}
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/global/import-esm.snippet.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { SnippetModule } from '../types';
+
+const snippet: SnippetModule = {
+  contexts: ['*'],
+  prefix: 'sn-import',
+  label: 'Import ESM module',
+  description: 'Dynamically import an ESM module by URL',
+  locales: {
+    'zh-CN': {
+      label: '导入 ESM 模块',
+      description: '按 URL 动态导入 ESM 模块',
+    },
+  },
+  content: `
+// Import an ESM module by URL
+// Works in yarn dev and yarn start
+const mod = await ctx.importAsync('https://cdn.jsdelivr.net/npm/lit-html@2/+esm');
+const { html, render } = mod;
+
+ctx.element.innerHTML = '';
+const container = document.createElement('div');
+container.style.padding = '8px';
+container.style.border = '1px dashed #999';
+ctx.element.append(container);
+
+render(html\`<span style="color:#52c41a;">lit-html loaded and rendered</span>\`, container);
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/global/message-error.snippet.ts

@@ -13,6 +13,12 @@ const snippet: SnippetModule = {
   prefix: 'sn-msg-error',
   label: 'Message error',
   description: 'Show an error toast message',
+  locales: {
+    'zh-CN': {
+      label: '错误消息提示',
+      description: '显示一条错误提示消息',
+    },
+  },
   content: `
 ctx.message.error(ctx.t('Operation failed'));
 `,

package/src/runjs-context/snippets/global/message-success.snippet.ts

@@ -13,6 +13,12 @@ const snippet: SnippetModule = {
   prefix: 'sn-msg',
   label: 'Message success',
   description: 'Show a success toast message',
+  locales: {
+    'zh-CN': {
+      label: '成功消息提示',
+      description: '显示一条成功提示消息',
+    },
+  },
   content: `
 ctx.message.success(ctx.t('Operation succeeded'));
 `,

package/src/runjs-context/snippets/global/notification-open.snippet.ts

@@ -7,11 +7,19 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
+import type { SnippetModule } from '../types';
+
+const snippet: SnippetModule = {
   contexts: ['*'],
   prefix: 'sn-notify',
   label: 'Open notification',
   description: 'Open an AntD notification with custom content',
+  locales: {
+    'zh-CN': {
+      label: '打开通知',
+      description: '展示一条自定义内容的通知',
+    },
+  },
   content: `
 ctx.notification.open({
   message: ctx.t('Notification title'),
@@ -19,3 +27,5 @@ ctx.notification.open({
 });
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/global/open-view-dialog.snippet.ts

@@ -14,12 +14,19 @@ const snippet: SnippetModule = {
   prefix: 'sn-open-dialog',
   label: 'Open view (dialog)',
   description: 'Open a view in dialog via ctx.openView',
+  locales: {
+    'zh-CN': {
+      label: '打开视图（对话框）',
+      description: '通过 ctx.openView 以对话框方式打开视图',
+    },
+  },
   content: `
-const popupUid = 'your-popup-uid';
+// Open a view as dialog and pass arguments at top-level
+const popupUid = ctx.model.uid + '-1'; // popupUid should be stable and better bound to ctx.model.uid
 await ctx.openView(popupUid, {
   mode: 'dialog',
-  viewUid: 'detail',
-  inputArgs: { foo: 'bar' },
+  title: ctx.t('Sample dialog'),
+  size: 'medium',
 });
 `,
 };

package/src/runjs-context/snippets/global/open-view-drawer.snippet.ts

@@ -14,12 +14,19 @@ const snippet: SnippetModule = {
   prefix: 'sn-open-drawer',
   label: 'Open view (drawer)',
   description: 'Open a view in drawer via ctx.openView',
+  locales: {
+    'zh-CN': {
+      label: '打开视图（抽屉）',
+      description: '通过 ctx.openView 以抽屉方式打开视图',
+    },
+  },
   content: `
-const popupUid = 'your-popup-uid';
+// Open a view as drawer and pass arguments at top-level
+const popupUid = ctx.model.uid + '-1'; // popupUid should be stable and better bound to ctx.model.uid
 await ctx.openView(popupUid, {
   mode: 'drawer',
-  viewUid: 'detail',
-  inputArgs: { foo: 'bar' },
+  title: ctx.t('Sample drawer'),
+  size: 'large',
 });
 `,
 };

package/src/runjs-context/snippets/global/query-selector.snippet.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { SnippetModule } from '../types';
+import { JSBlockRunJSContext } from '../../contexts/JSBlockRunJSContext';
+import { JSFieldRunJSContext } from '../../contexts/JSFieldRunJSContext';
+import { FormJSFieldItemRunJSContext } from '../../contexts/FormJSFieldItemRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSBlockRunJSContext, JSFieldRunJSContext, FormJSFieldItemRunJSContext],
+  prefix: 'sn-query-selector',
+  label: 'Query selector',
+  description: 'Find a child element inside ctx.element using querySelector',
+  locales: {
+    'zh-CN': {
+      label: '查询子元素',
+      description: '使用 querySelector 在 ctx.element 内查找子元素',
+    },
+  },
+  content: `
+const child = ctx.element.querySelector('.child-class');
+if (child) {
+  child.textContent = ctx.t('Hello from querySelector');
+}
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/global/require-amd.snippet.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 type { SnippetModule } from '../types';
+
+const snippet: SnippetModule = {
+  contexts: ['*'],
+  prefix: 'sn-require',
+  label: 'Load AMD module',
+  description: 'Dynamically load an AMD/RequireJS module by URL',
+  locales: {
+    'zh-CN': {
+      label: '加载 AMD 模块',
+      description: '通过 RequireJS 按 URL 动态加载 AMD 模块',
+    },
+  },
+  content: `
+// Load an external library (AMD/RequireJS)
+const dayjs = await ctx.requireAsync('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
+console.log('dayjs loaded:', dayjs?.default || dayjs);
+`,
+};
+
+export default snippet;

package/src/runjs-context/snippets/global/window-open.snippet.ts

@@ -7,13 +7,23 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
+import type { SnippetModule } from '../types';
+
+const snippet: SnippetModule = {
   contexts: ['*'],
   prefix: 'sn-window-open',
   label: 'Open new window',
   description: 'Safely open a new browser window/tab',
+  locales: {
+    'zh-CN': {
+      label: '打开新窗口',
+      description: '安全地打开一个新的浏览器窗口或标签页',
+    },
+  },
   content: `
 // Open a new window/tab
 window.open('https://example.com', '_blank');
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/index.ts

@@ -7,53 +7,192 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export type EngineSnippetMap = Record<string, () => Promise<any>>;
+import { RunJSContextRegistry } from '../registry';
 
-export const engineSnippets: EngineSnippetMap = {
+// Simple manual exports - no build-time magic needed
+const snippets: Record<string, () => Promise<any>> = {
   // global
   'global/message-success': () => import('./global/message-success.snippet'),
   'global/message-error': () => import('./global/message-error.snippet'),
-  'global/copy-to-clipboard': () => import('./global/copy-to-clipboard.snippet'),
-  'global/copy-record-json': () => import('./global/copy-record-json.snippet'),
-  'global/log-json-record': () => import('./global/log-json-record.snippet'),
-  'global/api-request-get': () => import('./global/api-request-get.snippet'),
-  'global/api-request-post': () => import('./global/api-request-post.snippet'),
-  'global/requireAsync': () => import('./global/requireAsync.snippet'),
-  'global/try-catch-async': () => import('./global/try-catch-async.snippet'),
-  'global/sleep': () => import('./global/sleep.snippet'),
+  'global/api-request': () => import('./global/api-request.snippet'),
+  'global/require-amd': () => import('./global/require-amd.snippet'),
+  'global/import-esm': () => import('./global/import-esm.snippet'),
   'global/notification-open': () => import('./global/notification-open.snippet'),
   'global/window-open': () => import('./global/window-open.snippet'),
-  'global/console-log-ctx': () => import('./global/console-log-ctx.snippet'),
   'global/open-view-drawer': () => import('./global/open-view-drawer.snippet'),
   'global/open-view-dialog': () => import('./global/open-view-dialog.snippet'),
-  'global/view-navigation-push': () => import('./global/view-navigation-push.snippet'),
+  'global/query-selector': () => import('./global/query-selector.snippet'),
+  'global/clipboard-copy-text': () => import('./global/clipboard-copy-text.snippet'),
   // libs
-  'libs/echarts-init': () => import('./libs/echarts-init.snippet'),
-  // scene/jsblock
-  'scene/jsblock/render-basic': () => import('./scene/jsblock/render-basic.snippet'),
-  'scene/jsblock/render-react': () => import('./scene/jsblock/render-react.snippet'),
-  'scene/jsblock/render-card': () => import('./scene/jsblock/render-card.snippet'),
-  'scene/jsblock/render-button-handler': () => import('./scene/jsblock/render-button-handler.snippet'),
-  'scene/jsblock/jsx-mount': () => import('./scene/jsblock/jsx-mount.snippet'),
-  'scene/jsblock/jsx-unmount': () => import('./scene/jsblock/jsx-unmount.snippet'),
-  'scene/jsblock/add-event-listener': () => import('./scene/jsblock/add-event-listener.snippet'),
-  'scene/jsblock/append-style': () => import('./scene/jsblock/append-style.snippet'),
-  // scene/jsfield
-  'scene/jsfield/innerHTML-value': () => import('./scene/jsfield/innerHTML-value.snippet'),
-  'scene/jsfield/format-number': () => import('./scene/jsfield/format-number.snippet'),
-  'scene/jsfield/color-by-value': () => import('./scene/jsfield/color-by-value.snippet'),
-  // scene/jsitem
-  'scene/jsitem/render-basic': () => import('./scene/jsitem/render-basic.snippet'),
-  // scene/actions
-  'scene/actions/record-id-message': () => import('./scene/actions/record-id-message.snippet'),
-  'scene/actions/run-action-basic': () => import('./scene/actions/run-action-basic.snippet'),
-  'scene/actions/collection-selected-count': () => import('./scene/actions/collection-selected-count.snippet'),
-  'scene/actions/iterate-selected-rows': () => import('./scene/actions/iterate-selected-rows.snippet'),
-  // scene/linkage
-  'scene/linkage/set-field-value': () => import('./scene/linkage/set-field-value.snippet'),
-  'scene/linkage/toggle-visible': () => import('./scene/linkage/toggle-visible.snippet'),
-  'scene/linkage/set-disabled': () => import('./scene/linkage/set-disabled.snippet'),
-  'scene/linkage/set-required': () => import('./scene/linkage/set-required.snippet'),
+  'scene/block/echarts-init': () => import('./scene/block/echarts-init.snippet'),
+  // scene/block
+  'scene/block/render-react': () => import('./scene/block/render-react.snippet'),
+  'scene/block/render-react-jsx': () => import('./scene/block/render-react-jsx.snippet'),
+  'scene/block/render-antd-icons': () => import('./scene/block/render-antd-icons.snippet'),
+  'scene/block/render-button-handler': () => import('./scene/block/render-button-handler.snippet'),
+  'scene/block/add-event-listener': () => import('./scene/block/add-event-listener.snippet'),
+  'scene/block/chartjs-bar': () => import('./scene/block/chartjs-bar.snippet'),
+  'scene/block/vue-component': () => import('./scene/block/vue-component.snippet'),
+  'scene/block/resource-example': () => import('./scene/block/resource-example.snippet'),
+  'scene/block/api-fetch-render-list': () => import('./scene/block/api-fetch-render-list.snippet'),
+  'scene/block/render-info-card': () => import('./scene/block/render-info-card.snippet'),
+  'scene/block/render-statistics': () => import('./scene/block/render-statistics.snippet'),
+  'scene/block/render-timeline': () => import('./scene/block/render-timeline.snippet'),
+  'scene/block/render-iframe': () => import('./scene/block/render-iframe.snippet'),
+  // scene/detail
+  'scene/detail/innerHTML-value': () => import('./scene/detail/innerHTML-value.snippet'),
+  'scene/detail/format-number': () => import('./scene/detail/format-number.snippet'),
+  'scene/detail/color-by-value': () => import('./scene/detail/color-by-value.snippet'),
+  'scene/detail/copy-to-clipboard': () => import('./scene/detail/copy-to-clipboard.snippet'),
+  'scene/detail/status-tag': () => import('./scene/detail/status-tag.snippet'),
+  'scene/detail/relative-time': () => import('./scene/detail/relative-time.snippet'),
+  'scene/detail/percentage-bar': () => import('./scene/detail/percentage-bar.snippet'),
+  // scene/form
+  'scene/form/render-basic': () => import('./scene/form/render-basic.snippet'),
+  'scene/form/set-field-value': () => import('./scene/form/set-field-value.snippet'),
+  'scene/form/toggle-visible': () => import('./scene/form/toggle-visible.snippet'),
+  'scene/form/set-disabled': () => import('./scene/form/set-disabled.snippet'),
+  'scene/form/set-required': () => import('./scene/form/set-required.snippet'),
+  'scene/form/calculate-total': () => import('./scene/form/calculate-total.snippet'),
+  'scene/form/conditional-required': () => import('./scene/form/conditional-required.snippet'),
+  'scene/form/cascade-select': () => import('./scene/form/cascade-select.snippet'),
+  'scene/form/toggle-multiple-fields': () => import('./scene/form/toggle-multiple-fields.snippet'),
+  'scene/form/copy-field-values': () => import('./scene/form/copy-field-values.snippet'),
+  // scene/table
+  'scene/table/cell-open-dialog': () => import('./scene/table/cell-open-dialog.snippet'),
+  'scene/table/concat-fields': () => import('./scene/table/concat-fields.snippet'),
+  'scene/table/collection-selected-count': () => import('./scene/table/collection-selected-count.snippet'),
+  'scene/table/iterate-selected-rows': () => import('./scene/table/iterate-selected-rows.snippet'),
+  'scene/table/destroy-selected': () => import('./scene/table/destroy-selected.snippet'),
+  'scene/table/export-selected-json': () => import('./scene/table/export-selected-json.snippet'),
 };
 
-export default engineSnippets;
+export default snippets;
+
+// Cohesive snippet helpers for clients (editor, etc.)
+type EngineSnippetEntry = {
+  name: string;
+  prefix?: string;
+  description?: string;
+  body: string;
+  ref: string;
+  group?: string;
+  groups?: string[];
+  scenes?: string[];
+};
+
+function deriveNameFromKey(key: string): string {
+  const parts = key.split('/');
+  return parts[parts.length - 1] || key;
+}
+
+function normalizeScenes(def: any, key: string): string[] {
+  if (Array.isArray(def?.scenes) && def.scenes.length) {
+    return def.scenes.map((scene: any) => String(scene).trim()).filter((scene: string) => scene.length > 0);
+  }
+  const parts = key.split('/');
+  if (parts[0] === 'scene' && parts[1]) {
+    return [parts[1]];
+  }
+  return [];
+}
+
+function computeGroups(def: any, key: string): string[] {
+  const scenes = normalizeScenes(def, key);
+  if (scenes.length) {
+    return scenes.map((scene) => `scene/${scene}`);
+  }
+  const parts = key.split('/');
+  if (!parts.length) return [];
+  const first = parts[0];
+  if (first === 'global' || first === 'libs') return [first];
+  if (first === 'scene' && parts.length >= 2) return [`${first}/${parts[1]}`];
+  if (parts.length >= 2) return [`${parts[0]}/${parts[1]}`];
+  return [parts[0]];
+}
+
+function resolveLocaleMeta(def: any, locale?: string) {
+  if (!locale || !def?.locales) return {};
+  const exact = def.locales[locale];
+  if (exact) return exact;
+  const normalized = locale.toLowerCase();
+  if (normalized !== locale && def.locales[normalized]) return def.locales[normalized];
+  const base = locale.split('-')[0];
+  if (base && def.locales[base]) return def.locales[base];
+  if (base) {
+    const lowerBase = base.toLowerCase();
+    if (def.locales[lowerBase]) return def.locales[lowerBase];
+  }
+  return {};
+}
+
+export async function getSnippetBody(ref: string): Promise<string> {
+  const loader = (snippets as any)[ref];
+  if (!loader) throw new Error(`[flow-engine] snippet not found: ${ref}`);
+  const mod = await loader();
+  const def = mod?.default;
+  // engine snippet modules export a SnippetModule as default
+  const content = def?.content ?? mod?.content ?? mod?.body ?? '';
+  return typeof content === 'string' ? content : String(content ?? '');
+}
+
+export async function listSnippetsForContext(
+  ctxClassName: string,
+  version = 'v1',
+  locale?: string,
+): Promise<EngineSnippetEntry[]> {
+  const entries: EngineSnippetEntry[] = [];
+  const allowedContextNames = new Set<string>();
+  if (typeof ctxClassName === 'string' && ctxClassName) allowedContextNames.add(ctxClassName);
+  try {
+    const resolvedCtor = RunJSContextRegistry['resolve'](version as any, ctxClassName);
+    if (resolvedCtor?.name) allowedContextNames.add(resolvedCtor.name);
+  } catch (_) {
+    // ignore resolution failure
+  }
+  await Promise.all(
+    Object.entries(snippets).map(async ([key, loader]) => {
+      const mod = await (loader as any)();
+      const def = mod?.default || {};
+      const body: any = def?.content ?? mod?.content;
+      if (typeof body !== 'string') return;
+      let ok = true;
+      if (Array.isArray(def?.contexts) && def.contexts.length) {
+        const ctxNames = def.contexts.map((item: any) => {
+          if (item === '*') return '*';
+          if (typeof item === 'string') return item;
+          if (typeof item === 'function') return item.name || '*';
+          if (item && typeof item === 'object' && typeof item.name === 'string') return item.name;
+          return String(item ?? '');
+        });
+        if (ctxClassName === '*') {
+          // '*' means return all snippets without filtering by context
+          ok = true;
+        } else {
+          ok = ctxNames.includes('*') || ctxNames.some((name: string) => allowedContextNames.has(name));
+        }
+      }
+      if (ok && Array.isArray(def?.versions) && def.versions.length) {
+        ok = def.versions.includes('*') || def.versions.includes(version);
+      }
+      if (!ok) return;
+      const localeMeta = resolveLocaleMeta(def, locale);
+      const name = localeMeta.label || def?.label || deriveNameFromKey(key);
+      const description = localeMeta.description ?? def?.description;
+      const prefix = def?.prefix || name;
+      const groups = computeGroups(def, key);
+      const scenes = normalizeScenes(def, key);
+      entries.push({
+        name,
+        prefix,
+        description,
+        body,
+        ref: key,
+        group: groups[0],
+        groups,
+        scenes,
+      });
+    }),
+  );
+  return entries;
+}

package/src/runjs-context/snippets/scene/{jsblock → block}/add-event-listener.snippet.ts

@@ -7,10 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-export default {
-  contexts: ['JSBlockRunJSContext'],
+import type { SnippetModule } from '../../types';
+import { JSBlockRunJSContext } from '../../../contexts/JSBlockRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSBlockRunJSContext],
   prefix: 'sn-jsb-click',
   label: 'Add click listener',
+  description: 'Render a button and bind a click event handler',
+  locales: {
+    'zh-CN': {
+      label: '添加点击监听',
+      description: '渲染按钮并绑定点击事件处理',
+    },
+  },
   content:
     `
 // Render a button and bind a click handler
@@ -27,3 +37,5 @@ if (btn) {
 }
 `,
 };
+
+export default snippet;

package/src/runjs-context/snippets/scene/block/api-fetch-render-list.snippet.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { SnippetModule } from '../../types';
+import { JSBlockRunJSContext } from '../../../contexts/JSBlockRunJSContext';
+
+const snippet: SnippetModule = {
+  contexts: [JSBlockRunJSContext],
+  prefix: 'sn-jsb-fetch-list',
+  label: 'Fetch & render list',
+  description: 'Fetch a small list via ctx.api and render basic HTML',
+  locales: {
+    'zh-CN': {
+      label: '拉取并渲染列表',
+      description: '使用 ctx.api 拉取少量数据，并渲染基础 HTML 列表',
+    },
+  },
+  content: `
+// Fetch users
+const { data } = await ctx.api.request({
+  url: 'users:list',
+  method: 'get',
+  params: { pageSize: 5 },
+});
+const rows = Array.isArray(data?.data) ? data.data : (Array.isArray(data) ? data : []);
+
+// Render as a simple HTML list
+ctx.element.innerHTML = [
+  '<div style="padding:12px">',
+  '<h4 style="margin:0 0 8px">' + ctx.t('Users') + '</h4>',
+  '<ul style="margin:0; padding-left:20px">',
+  ...rows.map((r, i) => '<li>#' + (i + 1) + ': ' + String((r && (r.nickname ?? r.username ?? r.id)) ?? '') + '</li>'),
+  '</ul>',
+  '</div>'
+].join('');
+`,
+};
+
+export default snippet;