plugin-build-visualization-block 0.1.1

package/src/client/hooks/useBuildPolling.ts

@@ -0,0 +1,215 @@
+import { useEffect, useRef, useState } from 'react';
+import { useAPIClient } from '@nocobase/client';
+
+import { BUILD_PHASES, BuildPhase, COLLECTION_NAME } from '../../shared/constants';
+
+/**
+ * The narrowed shape of a single `aiVisualizationBuilds:getResult` record, as
+ * consumed by the client while polling a build. Every field mirrors the server
+ * `getResult` body; the generated outputs (`blockSchema`/`blockSpec`/
+ * `adjustments`) are intentionally `unknown` because their concrete shape is
+ * only meaningful once the build reaches a terminal phase, and the polling hook
+ * is not responsible for interpreting them.
+ */
+export interface BuildResultRecord {
+  /** Primary key of the build record. */
+  id: string | number;
+  /** Coarse build status (`building` | `completed` | `error`). */
+  status: string;
+  /** Fine-grained phase used to drive the progress UI and stop polling. */
+  buildPhase: BuildPhase;
+  /** The generated Formily block schema once `buildPhase === 'completed'`. */
+  blockSchema: unknown;
+  /** The validated `BlockSpec` the schema was generated from. */
+  blockSpec: unknown;
+  /** The validator's remap/remove adjustments summary, when present. */
+  adjustments: unknown;
+  /** Whether the grounded fallback spec was used for this build. */
+  usedFallback: boolean;
+  /** A human-readable error message when the build failed, else `null`. */
+  errorMessage: string | null;
+}
+
+/** Options accepted by {@link useBuildPolling}. */
+export interface BuildPollingOptions {
+  /** Poll interval in milliseconds while the build is in progress. */
+  intervalMs?: number;
+  /** When `false`, polling is suspended (and any running timer is cleared). */
+  enabled?: boolean;
+}
+
+/**
+ * The reactive result returned by {@link useBuildPolling}.
+ *
+ * `phase`/`status` are convenience projections of `record` so callers can
+ * render the current phase without re-narrowing the record themselves.
+ */
+export type BuildPollingResult = {
+  /** Current build phase, or `undefined` before the first successful poll. */
+  phase: BuildPhase | undefined;
+  /** Current coarse status, or `undefined` before the first successful poll. */
+  status: string | undefined;
+  /** The latest polled record, or `undefined` before the first poll. */
+  record: BuildResultRecord | undefined;
+  /** The most recent polling error, cleared on the next successful poll. */
+  error: Error | undefined;
+  /** Whether a poll request is currently in flight. */
+  loading: boolean;
+};
+
+/** Default poll interval (Req 10.5): ~2 s while a build is in progress. */
+const DEFAULT_INTERVAL_MS = 2000;
+
+/** Phases at which a build is finished and polling must stop. */
+function isTerminalPhase(phase: BuildPhase | undefined): boolean {
+  return phase === 'completed' || phase === 'failed';
+}
+
+/** Type guard narrowing an arbitrary value to a known {@link BuildPhase}. */
+function isBuildPhase(value: unknown): value is BuildPhase {
+  return typeof value === 'string' && (BUILD_PHASES as string[]).includes(value);
+}
+
+/**
+ * Safely unwrap the API client response to the record body. NocoBase action
+ * responses are double-wrapped (`res.data.data`), so both levels are checked
+ * structurally without resorting to `any`.
+ */
+function extractResponseData(res: unknown): unknown {
+  if (res && typeof res === 'object') {
+    const outer = (res as { data?: unknown }).data;
+    if (outer && typeof outer === 'object') {
+      return (outer as { data?: unknown }).data;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Narrow the untyped `getResult` payload to a {@link BuildResultRecord}. Returns
+ * `undefined` when the payload is missing or lacks a usable primary key, so the
+ * caller never overwrites good state with a malformed response.
+ */
+function narrowRecord(value: unknown): BuildResultRecord | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const v = value as Record<string, unknown>;
+  const id = v.id;
+  if (typeof id !== 'string' && typeof id !== 'number') {
+    return undefined;
+  }
+  return {
+    id,
+    status: typeof v.status === 'string' ? v.status : '',
+    buildPhase: isBuildPhase(v.buildPhase) ? v.buildPhase : 'idle',
+    blockSchema: v.blockSchema ?? undefined,
+    blockSpec: v.blockSpec ?? undefined,
+    adjustments: v.adjustments ?? undefined,
+    usedFallback: v.usedFallback === true,
+    errorMessage: typeof v.errorMessage === 'string' ? v.errorMessage : null,
+  };
+}
+
+/**
+ * Poll a build record until it reaches a terminal phase.
+ *
+ * Polls `aiVisualizationBuilds:getResult` every `intervalMs` (default 2000ms)
+ * while the build is in progress and stops automatically when:
+ * - the record phase is terminal (`completed` or `failed`),
+ * - `options.enabled === false`, or
+ * - `buildId` is `undefined`.
+ *
+ * The timer is cleared on unmount and whenever polling stops, and a tick is
+ * skipped while a previous request is still in flight (a ref guard prevents
+ * overlapping requests). Returns the current `phase`, `status`, `record`,
+ * `error`, and `loading` state.
+ *
+ * _Requirements: 10.5_
+ */
+export function useBuildPolling(
+  buildId: string | number | undefined,
+  options: BuildPollingOptions = {},
+): BuildPollingResult {
+  const { intervalMs = DEFAULT_INTERVAL_MS, enabled = true } = options;
+  const api = useAPIClient();
+
+  const [record, setRecord] = useState<BuildResultRecord | undefined>(undefined);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [loading, setLoading] = useState(false);
+
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const inFlightRef = useRef(false);
+
+  useEffect(() => {
+    const clearTimer = () => {
+      if (timerRef.current !== null) {
+        clearInterval(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+
+    // Nothing to poll: suspend and surface a clean, idle state.
+    if (!enabled || buildId === undefined) {
+      clearTimer();
+      setLoading(false);
+      return clearTimer;
+    }
+
+    let cancelled = false;
+
+    const tick = async (): Promise<void> => {
+      // Skip this tick if a request is still outstanding (ref guard).
+      if (inFlightRef.current) {
+        return;
+      }
+      inFlightRef.current = true;
+      setLoading(true);
+      try {
+        const res = await api.resource(COLLECTION_NAME).getResult({ filterByTk: buildId });
+        if (cancelled) {
+          return;
+        }
+        const next = narrowRecord(extractResponseData(res));
+        if (next) {
+          setRecord(next);
+          setError(undefined);
+          // Stop once the build has finished; nothing more will change.
+          if (isTerminalPhase(next.buildPhase)) {
+            clearTimer();
+          }
+        }
+      } catch (e) {
+        if (!cancelled) {
+          setError(e instanceof Error ? e : new Error(String(e)));
+        }
+      } finally {
+        inFlightRef.current = false;
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    // `tick` never rejects (it handles its own errors), so it is safe to invoke
+    // directly from the effect and the interval callback.
+    // Poll immediately, then on the interval until a terminal phase is reached.
+    tick();
+    timerRef.current = setInterval(tick, intervalMs);
+
+    return () => {
+      cancelled = true;
+      clearTimer();
+    };
+  }, [api, buildId, enabled, intervalMs]);
+
+  return {
+    phase: record?.buildPhase,
+    status: record?.status,
+    record,
+    error,
+    loading,
+  };
+}
+
+export default useBuildPolling;

package/src/client/index.tsx

@@ -0,0 +1,2 @@
+export { default } from './plugin';
+export * from './plugin';

package/src/client/locale.ts

@@ -0,0 +1,18 @@
+import { useApp } from '@nocobase/client';
+import { useCallback } from 'react';
+import { name } from '../locale/namespace';
+
+export const namespace = name;
+
+export function useT() {
+  const app = useApp();
+  return useCallback(
+    (str: string, options?: Record<string, unknown>): string =>
+      app.i18n.t(str, { ns: [namespace, 'client'], ...options }) as unknown as string,
+    [app.i18n],
+  );
+}
+
+export function tStr(key: string) {
+  return `{{t(${JSON.stringify(key)}, { ns: ['${namespace}', 'client'], nsMode: 'fallback' })}}`;
+}

package/src/client/plugin.tsx

@@ -0,0 +1,90 @@
+import { Plugin } from '@nocobase/client';
+
+import { BuildVisualizationBlockInitializer } from './BuildVisualizationBlockInitializer';
+import { SettingsPage } from './SettingsPage';
+
+/**
+ * Block initializers the "Build Visualization Block" item is added to so it is
+ * reachable from desktop pages, both popup "add block" menus, and mobile pages.
+ */
+const BLOCK_INITIALIZERS = [
+  'page:addBlock',
+  'popup:common:addBlock',
+  'popup:addNew:addBlock',
+  'mobile:addBlock',
+] as const;
+
+/** Item key within the `dataBlocks` group of each block initializer. */
+const INITIALIZER_ITEM_KEY = 'dataBlocks.buildVisualizationBlock';
+
+/**
+ * Client-side plugin for `plugin-build-visualization-block`.
+ *
+ * - `afterAdd` performs soft availability checks for the data-visualization and
+ *   AI plugins (the block leans on both at build/render time). Missing plugins
+ *   are reported with `console.warn` and never throw, so this plugin still loads
+ *   in environments where they are absent.
+ * - `load` registers the {@link BuildVisualizationBlockInitializer} component and
+ *   wires it into the "Add block" menus.
+ * - `remove` unregisters those menu items (Req 8.4).
+ *
+ * This plugin uses the v1 client runtime (`@nocobase/client`); it must not
+ * import from the v2 runtime.
+ */
+export class PluginBuildVisualizationBlockClient extends Plugin {
+  // Req 8.1: surface (but do not enforce) the soft dependencies on
+  // data-visualization and AI so a misconfigured environment is diagnosable.
+  async afterAdd() {
+    const { pm } = this.app;
+
+    try {
+      const dataVisualization = pm.get('@nocobase/plugin-data-visualization') || pm.get('plugin-data-visualization');
+      if (!dataVisualization) {
+        console.warn('[plugin-build-visualization-block] plugin-data-visualization is not available');
+      }
+    } catch {
+      console.warn('[plugin-build-visualization-block] plugin-data-visualization is not available');
+    }
+
+    try {
+      const ai = pm.get('@nocobase/plugin-ai') || pm.get('plugin-ai');
+      if (!ai) {
+        console.warn('[plugin-build-visualization-block] plugin-ai is not available');
+      }
+    } catch {
+      console.warn('[plugin-build-visualization-block] plugin-ai is not available');
+    }
+  }
+
+  async load() {
+    this.app.addComponents({ BuildVisualizationBlockInitializer });
+
+    this.app.pluginSettingsManager.add('plugin-build-visualization-block', {
+      icon: 'DashboardOutlined',
+      title: this.t('Build Visualization Block'),
+      Component: SettingsPage,
+      aclSnippet: 'pm.plugin-build-visualization-block.settings',
+    });
+
+    // NOTE: deliberately omit `type: 'item'` so the entry renders as a standard
+    // clickable item in the "Add block" dropdown (see
+    // plugin-setup-architecture-instructions.md, "type: 'item' trap").
+    BLOCK_INITIALIZERS.forEach((initializer) => {
+      this.app.schemaInitializerManager.addItem(initializer, INITIALIZER_ITEM_KEY, {
+        name: 'buildVisualizationBlock',
+        title: '{{t("Build Visualization Block", { ns: "plugin-build-visualization-block" })}}',
+        Component: 'BuildVisualizationBlockInitializer',
+      });
+    });
+  }
+
+  // Req 8.4: tear down the registered items on uninstall/disable.
+  async remove() {
+    this.app.pluginSettingsManager.remove('plugin-build-visualization-block');
+    BLOCK_INITIALIZERS.forEach((initializer) => {
+      this.app.schemaInitializerManager.removeItem(initializer, INITIALIZER_ITEM_KEY);
+    });
+  }
+}
+
+export default PluginBuildVisualizationBlockClient;

package/src/client-v2/index.tsx

@@ -0,0 +1 @@
+export { default } from './plugin';

package/src/client-v2/plugin.tsx

@@ -0,0 +1,24 @@
+import { Plugin, Application } from '@nocobase/client-v2';
+import React from 'react';
+
+export class PluginBuildVisualizationBlockClient extends Plugin<Record<string, never>, Application> {
+  async load() {
+    this.pluginSettingsManager.addMenuItem({
+      key: 'plugin-build-visualization-block',
+      title: this.t('Build Visualization Block'),
+      icon: 'DashboardOutlined',
+      aclSnippet: 'pm.plugin-build-visualization-block.settings',
+    });
+
+    this.pluginSettingsManager.addPageTabItem({
+      menuKey: 'plugin-build-visualization-block',
+      key: 'index',
+      title: this.t('Build Visualization Block'),
+      
+      componentLoader: () => import('../client/SettingsPage').then(m => ({ default: m.SettingsPage })),
+    });
+
+  }
+}
+
+export default PluginBuildVisualizationBlockClient;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './server';
+export { default } from './server';

package/src/locale/en-US.json

@@ -0,0 +1,45 @@
+{
+  "Build Visualization Block": "Build Visualization Block",
+  "Data source": "Data source",
+  "Collections": "Collections",
+  "Requirement": "Requirement",
+  "Describe the block you want to build": "Describe the block you want to build",
+  "AI service": "AI service",
+  "Model": "Model",
+  "At least one collection is required": "At least one collection is required",
+  "You can select at most {{max}} collections": "You can select at most {{max}} collections",
+  "Requirement description is required": "Requirement description is required",
+  "Requirement must be at most {{max}} characters": "Requirement must be at most {{max}} characters",
+  "AI service and model are required": "AI service and model are required",
+  "The AI service is unavailable": "The AI service is unavailable",
+  "Idle": "Idle",
+  "Queued": "Queued",
+  "Analyzing": "Analyzing",
+  "Generating": "Generating",
+  "Completed": "Completed",
+  "Failed": "Failed",
+  "Build": "Build",
+  "Insert": "Insert",
+  "Regenerate": "Regenerate",
+  "Cancel": "Cancel",
+  "Preview": "Preview",
+  "A fallback block was generated": "A fallback block was generated",
+  "Some fields were adjusted to match the collection": "Some fields were adjusted to match the collection",
+  "Failed to load the list": "Failed to load the list",
+  "Retry": "Retry",
+  "The requirement could not be saved": "The requirement could not be saved",
+  "A maximum of {{max}} collections can be selected": "A maximum of {{max}} collections can be selected",
+  "A requirement is required": "A requirement is required",
+  "The requirement must be {{max}} characters or fewer": "The requirement must be {{max}} characters or fewer",
+  "An LLM service and model are required": "An LLM service and model are required",
+  "You do not have permission to read collection \"{{collection}}\"": "You do not have permission to read collection \"{{collection}}\"",
+  "You do not have permission to read this build": "You do not have permission to read this build",
+  "A build id is required": "A build id is required",
+  "Build record not found": "Build record not found",
+  "Default collections": "Default collections",
+  "Default AI service": "Default AI service",
+  "Default model": "Default model",
+  "Enable AI tool": "Enable AI tool",
+  "Save": "Save",
+  "Saved successfully": "Saved successfully"
+}

package/src/locale/namespace.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared namespace constant.
+ * Matches the namespace used in inline schema strings
+ * such as {{t("...", { ns: "plugin-build-visualization-block" })}}.
+ */
+export const name = 'plugin-build-visualization-block';

package/src/locale/vi-VN.json

@@ -0,0 +1,46 @@
+{
+  "Build Visualization Block": "Khối tạo trực quan hóa",
+  "Data source": "Nguồn dữ liệu",
+  "Collections": "Bộ sưu tập",
+  "Requirement": "Yêu cầu",
+  "Describe the block you want to build": "Mô tả khối bạn muốn tạo",
+  "AI service": "Dịch vụ AI",
+  "Model": "Mô hình",
+  "At least one collection is required": "Cần chọn ít nhất một bộ sưu tập",
+  "You can select at most {{max}} collections": "Bạn chỉ có thể chọn tối đa {{max}} bộ sưu tập",
+  "Requirement description is required": "Mô tả yêu cầu là bắt buộc",
+  "Requirement must be at most {{max}} characters": "Yêu cầu chỉ được tối đa {{max}} ký tự",
+  "AI service and model are required": "Dịch vụ AI và mô hình là bắt buộc",
+  "The AI service is unavailable": "Dịch vụ AI không khả dụng",
+  "Idle": "Nhàn rỗi",
+  "Queued": "Đang chờ xử lý",
+  "Analyzing": "Đang phân tích",
+  "Generating": "Đang tạo",
+  "Completed": "Hoàn thành",
+  "Failed": "Thất bại",
+  "Build": "Tạo",
+  "Insert": "Chèn",
+  "Regenerate": "Tạo lại",
+  "Cancel": "Hủy",
+  "Preview": "Xem trước",
+  "A fallback block was generated": "Đã tạo một khối dự phòng",
+  "Some fields were adjusted to match the collection": "Một số trường đã được điều chỉnh để khớp với bộ sưu tập",
+  "Failed to load the list": "Không tải được danh sách",
+  "Retry": "Thử lại",
+  "The requirement could not be saved": "Không thể lưu yêu cầu",
+  "A maximum of {{max}} collections can be selected": "Có thể chọn tối đa {{max}} bộ sưu tập",
+  "A requirement is required": "Yêu cầu là bắt buộc",
+  "The requirement must be {{max}} characters or fewer": "Yêu cầu phải có tối đa {{max}} ký tự",
+  "An LLM service and model are required": "Dịch vụ AI và mô hình là bắt buộc",
+  "You do not have permission to read collection \"{{collection}}\"": "Bạn không có quyền đọc bộ sưu tập \"{{collection}}\"",
+  "You do not have permission to read this build": "Bạn không có quyền đọc bản dựng này",
+  "A build id is required": "ID bản dựng là bắt buộc",
+  "Build record not found": "Không tìm thấy bản ghi bản dựng"
+  ,
+  "Default collections": "Default collections",
+  "Default AI service": "Default AI service",
+  "Default model": "Default model",
+  "Enable AI tool": "Enable AI tool",
+  "Save": "Save",
+  "Saved successfully": "Saved successfully"
+}

package/src/locale/zh-CN.json

@@ -0,0 +1,46 @@
+{
+  "Build Visualization Block": "构建可视化区块",
+  "Data source": "数据源",
+  "Collections": "数据表",
+  "Requirement": "需求",
+  "Describe the block you want to build": "描述您想要构建的区块",
+  "AI service": "AI 服务",
+  "Model": "模型",
+  "At least one collection is required": "至少需要选择一个数据表",
+  "You can select at most {{max}} collections": "最多只能选择 {{max}} 个数据表",
+  "Requirement description is required": "需求描述不能为空",
+  "Requirement must be at most {{max}} characters": "需求描述最多 {{max}} 个字符",
+  "AI service and model are required": "AI 服务和模型为必填项",
+  "The AI service is unavailable": "AI 服务不可用",
+  "Idle": "空闲",
+  "Queued": "排队中",
+  "Analyzing": "分析中",
+  "Generating": "生成中",
+  "Completed": "已完成",
+  "Failed": "失败",
+  "Build": "构建",
+  "Insert": "插入",
+  "Regenerate": "重新生成",
+  "Cancel": "取消",
+  "Preview": "预览",
+  "A fallback block was generated": "已生成备用区块",
+  "Some fields were adjusted to match the collection": "部分字段已调整以匹配数据表",
+  "Failed to load the list": "加载列表失败",
+  "Retry": "重试",
+  "The requirement could not be saved": "无法保存需求",
+  "A maximum of {{max}} collections can be selected": "最多只能选择 {{max}} 个数据表",
+  "A requirement is required": "需求不能为空",
+  "The requirement must be {{max}} characters or fewer": "需求描述最多 {{max}} 个字符",
+  "An LLM service and model are required": "AI 服务和模型为必填项",
+  "You do not have permission to read collection \"{{collection}}\"": "您没有读取数据表“{{collection}}”的权限",
+  "You do not have permission to read this build": "您没有读取此构建的权限",
+  "A build id is required": "构建 ID 为必填项",
+  "Build record not found": "未找到构建记录"
+  ,
+  "Default collections": "Default collections",
+  "Default AI service": "Default AI service",
+  "Default model": "Default model",
+  "Enable AI tool": "Enable AI tool",
+  "Save": "Save",
+  "Saved successfully": "Saved successfully"
+}