plugin-build-visualization-block 0.1.1

package/src/client/BuildForm.tsx

@@ -0,0 +1,376 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { Alert, Button, Input, Space, Spin, Typography } from 'antd';
+import { ISchema, useAPIClient, useApp } from '@nocobase/client';
+import { createForm } from '@formily/core';
+import { Field, FormProvider } from '@formily/react';
+
+import {
+  CollectionMultiSelect,
+  CollectionMultiSelectValue,
+  LLMServiceSelect,
+  ModelSelect,
+  BuildPhaseTag,
+} from './components';
+import { PreviewPanel } from './PreviewPanel';
+import { useBuildPolling } from './hooks/useBuildPolling';
+import { useT } from './locale';
+import { COLLECTION_NAME, MAX_COLLECTIONS, MAX_REQUIREMENT_CHARS, SETTINGS_COLLECTION_NAME } from '../shared/constants';
+
+/**
+ * Props consumed by {@link BuildForm}.
+ *
+ * This is the stable seam between the block initializer (task 10.2) and the
+ * full build form (task 9.2). The initializer hosts the form inside a modal and
+ * passes:
+ * - `onInsert` — called with the generated Formily block schema once the user
+ *   confirms a build; the initializer forwards it to `useSchemaInitializer().insert`.
+ * - `onClose` — called when the form is dismissed without inserting anything.
+ *
+ * `BuildForm` renders only the form/flow body (no modal of its own) because the
+ * initializer already owns the surrounding `Modal`.
+ */
+export type BuildFormProps = {
+  /** Insert the generated block schema into the active page/popup. */
+  onInsert: (schema: ISchema) => void;
+  /** Dismiss the form without inserting. */
+  onClose: () => void;
+};
+
+/**
+ * Client-side validation errors keyed by the field they belong to. A missing
+ * key means that field is currently valid.
+ */
+interface FormErrors {
+  requirement?: string;
+  collections?: string;
+  ai?: string;
+  /** A submit-time error not tied to a single field (e.g. request failure). */
+  submit?: string;
+}
+
+/**
+ * Read a string value out of the (loosely-typed) Formily `form.values` bag
+ * without leaking `any` into call sites.
+ */
+function readStringValue(values: unknown, key: string): string {
+  if (values && typeof values === 'object') {
+    const candidate = (values as Record<string, unknown>)[key];
+    if (typeof candidate === 'string') {
+      return candidate;
+    }
+  }
+  return '';
+}
+
+/**
+ * Safely pull the created build record id out of the `build` action response.
+ * NocoBase action responses are double-wrapped (`res.data.data`), so both
+ * levels are checked structurally and the id is normalized to a string.
+ */
+function extractBuildId(res: unknown): string | undefined {
+  if (res && typeof res === 'object') {
+    const outer = (res as { data?: unknown }).data;
+    if (outer && typeof outer === 'object') {
+      const body = (outer as { data?: unknown }).data;
+      if (body && typeof body === 'object') {
+        const id = (body as { id?: unknown }).id;
+        if (typeof id === 'string' || typeof id === 'number') {
+          return String(id);
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+interface BuildDefaults {
+  defaultDataSource?: string;
+  defaultCollections?: string[];
+  defaultLLMService?: string;
+  defaultModel?: string;
+}
+
+function normalizeDefaults(value: unknown): BuildDefaults {
+  const source = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+  return {
+    defaultDataSource: typeof source.defaultDataSource === 'string' ? source.defaultDataSource : undefined,
+    defaultCollections: Array.isArray(source.defaultCollections)
+      ? source.defaultCollections.filter((item): item is string => typeof item === 'string')
+      : [],
+    defaultLLMService: typeof source.defaultLLMService === 'string' ? source.defaultLLMService : undefined,
+    defaultModel: typeof source.defaultModel === 'string' ? source.defaultModel : undefined,
+  };
+}
+
+/**
+ * The natural-language build form (Req 1.4, 1.6, 3.1, 3.2, 3.3, 4.3, 4.4).
+ *
+ * Field-wiring decision: the two AI selectors (`LLMServiceSelect`,
+ * `ModelSelect`) rely on Formily context — `ModelSelect` observes
+ * `form.values.llmService` and `LLMServiceSelect` resets the sibling `.model`
+ * field — so they are rendered inside a small Formily `FormProvider` whose
+ * values expose `llmService`/`model`. The `requirement` textarea and the
+ * data-source/collections picker (`CollectionMultiSelect`, an object-valued
+ * controlled component) are kept in plain React state, which is both simpler
+ * and avoids awkwardly adapting an object-valued field into Formily. This is
+ * the cleaner of the two approaches the design allows.
+ *
+ * Flow: idle/editing → (submit) building → completed (preview) | failed (retry).
+ */
+export const BuildForm: React.FC<BuildFormProps> = ({ onInsert, onClose }) => {
+  const t = useT();
+  const api = useAPIClient();
+  const app = useApp();
+
+  // Formily form backing the AI selectors only (llmService + model).
+  const form = useMemo(() => createForm(), []);
+
+  // Plain-state fields.
+  const [requirement, setRequirement] = useState('');
+  const [collectionValue, setCollectionValue] = useState<CollectionMultiSelectValue>({
+    collections: [],
+  });
+  const [errors, setErrors] = useState<FormErrors>({});
+
+  // Build lifecycle state.
+  const [buildId, setBuildId] = useState<string | undefined>(undefined);
+  const [submitting, setSubmitting] = useState(false);
+  // `building` drives the in-progress view and is also the polling switch. It
+  // is set on submit/retry and cleared once the build reaches a terminal phase.
+  const [building, setBuilding] = useState(false);
+
+  const { phase, record } = useBuildPolling(buildId, {
+    enabled: Boolean(buildId) && building,
+  });
+
+  // Stop polling and leave the building view once the build is terminal.
+  useEffect(() => {
+    if (phase === 'completed' || phase === 'failed') {
+      setBuilding(false);
+    }
+  }, [phase]);
+
+  useEffect(() => {
+    let active = true;
+
+    const loadDefaults = async () => {
+      try {
+        const response = await api.resource(SETTINGS_COLLECTION_NAME).publicGet();
+        if (!active) {
+          return;
+        }
+        const defaults = normalizeDefaults((response as { data?: { data?: unknown } }).data?.data);
+        setCollectionValue({
+          dataSource: defaults.defaultDataSource,
+          collections: defaults.defaultCollections ?? [],
+        });
+        form.setValues({
+          llmService: defaults.defaultLLMService,
+          model: defaults.defaultModel,
+        });
+      } catch (error) {
+        console.warn('[plugin-build-visualization-block] Failed to load default settings:', error);
+      }
+    };
+
+    loadDefaults();
+    return () => {
+      active = false;
+    };
+  }, [api, form]);
+
+  // AI availability (Req 4.4): the build needs the AI plugin to be present.
+  const aiAvailable = useMemo<boolean>(() => {
+    const pm = app.pm;
+    return Boolean(pm.get('ai') || pm.get('@nocobase/plugin-ai') || pm.get('plugin-ai'));
+  }, [app]);
+
+  const dataSource = collectionValue.dataSource;
+  const collections = useMemo(() => collectionValue.collections ?? [], [collectionValue]);
+
+  /** Validate the editable inputs; returns the collected errors. */
+  const validate = useCallback((): FormErrors => {
+    const next: FormErrors = {};
+
+    const trimmedRequirement = requirement.trim();
+    if (!trimmedRequirement) {
+      next.requirement = t('Requirement description is required');
+    } else if (requirement.length > MAX_REQUIREMENT_CHARS) {
+      next.requirement = t('Requirement must be at most {{max}} characters', {
+        max: MAX_REQUIREMENT_CHARS,
+      });
+    }
+
+    if (collections.length < 1) {
+      next.collections = t('At least one collection is required');
+    } else if (collections.length > MAX_COLLECTIONS) {
+      next.collections = t('You can select at most {{max}} collections', {
+        max: MAX_COLLECTIONS,
+      });
+    }
+
+    const llmService = readStringValue(form.values, 'llmService');
+    const model = readStringValue(form.values, 'model');
+    if (!llmService || !model) {
+      next.ai = t('AI service and model are required');
+    }
+
+    return next;
+  }, [requirement, collections, form, t]);
+
+  const handleSubmit = useCallback(async () => {
+    // Re-validate AI availability defensively (Req 4.4).
+    if (!aiAvailable) {
+      return;
+    }
+
+    const validationErrors = validate();
+    if (Object.keys(validationErrors).length > 0) {
+      // Retain values; surface inline messages (Req 1.4/1.6/3.2/3.3/4.3).
+      setErrors(validationErrors);
+      return;
+    }
+    setErrors({});
+
+    const values = {
+      requirement: requirement.trim(),
+      dataSource,
+      collections,
+      primaryCollection: collections[0],
+      llmService: readStringValue(form.values, 'llmService'),
+      model: readStringValue(form.values, 'model'),
+    };
+
+    setSubmitting(true);
+    try {
+      const res = await api.resource(COLLECTION_NAME).build({ values });
+      const id = extractBuildId(res);
+      if (!id) {
+        setErrors({ submit: t('The requirement could not be saved') });
+        return;
+      }
+      setBuildId(id);
+      setBuilding(true);
+    } catch {
+      setErrors({ submit: t('The requirement could not be saved') });
+    } finally {
+      setSubmitting(false);
+    }
+  }, [aiAvailable, validate, requirement, dataSource, collections, form, api, t]);
+
+  // Regenerate/Retry: re-queue the same record and resume polling its id.
+  const handleRegenerate = useCallback(async () => {
+    if (!buildId) {
+      return;
+    }
+    setErrors({});
+    setSubmitting(true);
+    try {
+      await api.resource(COLLECTION_NAME).retry({ filterByTk: buildId });
+      setBuilding(true);
+    } catch (error) {
+      setErrors({ submit: t('The requirement could not be saved') });
+    } finally {
+      setSubmitting(false);
+    }
+  }, [api, buildId, t]);
+
+  // ---- Completed: render the preview. -------------------------------------
+  if (buildId && !building && phase === 'completed' && record) {
+    return (
+      <PreviewPanel
+        schema={record.blockSchema as ISchema}
+        usedFallback={record.usedFallback}
+        adjustments={record.adjustments}
+        onInsert={onInsert}
+        onRegenerate={handleRegenerate}
+        onCancel={onClose}
+        loading={false}
+      />
+    );
+  }
+
+  // ---- Failed: show the error and offer a retry. --------------------------
+  if (buildId && !building && phase === 'failed') {
+    return (
+      <Space direction="vertical" style={{ width: '100%' }} size="middle">
+        <Alert type="error" showIcon message={record?.errorMessage || t('The requirement could not be saved')} />
+        <Space>
+          <Button type="primary" onClick={handleRegenerate} loading={submitting}>
+            {t('Retry')}
+          </Button>
+          <Button onClick={onClose}>{t('Cancel')}</Button>
+        </Space>
+      </Space>
+    );
+  }
+
+  // ---- Building: show the current phase + a spinner. ----------------------
+  if (buildId && building) {
+    return (
+      <Space direction="vertical" align="center" style={{ width: '100%', padding: 24 }} size="middle">
+        <Spin aria-label={t('Generating')} />
+        <Space>
+          <BuildPhaseTag value={phase} />
+          <Typography.Text type="secondary">{t('Generating')}</Typography.Text>
+        </Space>
+      </Space>
+    );
+  }
+
+  // ---- Idle/editing: render the form. -------------------------------------
+  return (
+    <Space direction="vertical" style={{ width: '100%' }} size="middle">
+      {!aiAvailable ? <Alert type="warning" showIcon message={t('The AI service is unavailable')} /> : null}
+
+      <div>
+        <Typography.Text strong>{t('Requirement')}</Typography.Text>
+        <Input.TextArea
+          aria-label={t('Requirement')}
+          placeholder={t('Describe the block you want to build')}
+          value={requirement}
+          onChange={(event) => setRequirement(event.target.value)}
+          showCount
+          maxLength={MAX_REQUIREMENT_CHARS}
+          autoSize={{ minRows: 3, maxRows: 8 }}
+          status={errors.requirement ? 'error' : undefined}
+        />
+        {errors.requirement ? <Typography.Text type="danger">{errors.requirement}</Typography.Text> : null}
+      </div>
+
+      <div>
+        <Typography.Text strong>{t('Collections')}</Typography.Text>
+        <CollectionMultiSelect value={collectionValue} onChange={setCollectionValue} />
+        {errors.collections ? <Typography.Text type="danger">{errors.collections}</Typography.Text> : null}
+      </div>
+
+      <FormProvider form={form}>
+        <div>
+          <Typography.Text strong>{t('AI service')}</Typography.Text>
+          <Field
+            name="llmService"
+            component={[LLMServiceSelect, { placeholder: t('AI service'), style: { width: '100%' } }]}
+          />
+        </div>
+        <div>
+          <Typography.Text strong>{t('Model')}</Typography.Text>
+          <Field name="model" component={[ModelSelect, { placeholder: t('Model'), style: { width: '100%' } }]} />
+        </div>
+      </FormProvider>
+
+      {errors.ai ? <Typography.Text type="danger">{errors.ai}</Typography.Text> : null}
+      {errors.submit ? <Alert type="error" showIcon message={errors.submit} /> : null}
+
+      <Space>
+        <Button type="primary" onClick={handleSubmit} loading={submitting} disabled={!aiAvailable}>
+          {t('Build')}
+        </Button>
+        <Button onClick={onClose} disabled={submitting}>
+          {t('Cancel')}
+        </Button>
+      </Space>
+    </Space>
+  );
+};
+
+export default BuildForm;

package/src/client/BuildVisualizationBlockInitializer.tsx

@@ -0,0 +1,81 @@
+import { DashboardOutlined } from '@ant-design/icons';
+import type { ISchema } from '@nocobase/client';
+import {
+  SchemaInitializerItem,
+  useACLRoleContext,
+  useSchemaInitializer,
+  useSchemaInitializerItem,
+} from '@nocobase/client';
+import { Modal } from 'antd';
+import React, { useCallback, useState } from 'react';
+
+import { BuildForm } from './BuildForm';
+import { useT } from './locale';
+import { ACTIONS } from '../shared/constants';
+
+/**
+ * Block-menu item that launches the AI build flow.
+ *
+ * Unlike `plugin-visualization-templates`' initializer — which builds a schema
+ * from a template registry the moment it is clicked — this initializer opens
+ * the {@link BuildForm}. The form collects the collections, requirement, and
+ * LLM settings, runs the asynchronous build, and (on confirm) hands back a
+ * generated block schema which we insert into the active page/popup.
+ *
+ * Rendering notes:
+ * - This renders as a plain clickable `SchemaInitializerItem` (collections are
+ *   chosen inside the form, not in the menu, so `DataBlockInitializer`'s
+ *   collection picker is not needed here).
+ * - The schema-initializer item registration (task 10.3) must NOT pass
+ *   `type: 'item'`, or the entry can fail to render as a clickable menu item
+ *   (see plugin-setup-architecture-instructions.md). This component is designed
+ *   to be that clickable item.
+ *
+ * Permission (Req 8.3): the item is hidden when the current role cannot perform
+ * the plugin's build action. We resolve visibility with
+ * `useACLRoleContext().parseAction`, mirroring how the reference initializer
+ * derives its `filter`.
+ */
+export const BuildVisualizationBlockInitializer: React.FC = () => {
+  const itemConfig = useSchemaInitializerItem();
+  const { insert } = useSchemaInitializer();
+  const { parseAction } = useACLRoleContext();
+  const t = useT();
+  const [open, setOpen] = useState(false);
+
+  const handleOpen = useCallback(() => setOpen(true), []);
+  const handleClose = useCallback(() => setOpen(false), []);
+
+  // Req 8.2: confirming a build inserts the generated schema, then closes.
+  const handleInsert = useCallback(
+    (schema: ISchema) => {
+      setOpen(false);
+      insert(schema);
+    },
+    [insert],
+  );
+
+  // Req 8.3: hide the menu item when the role lacks permission to the plugin's
+  // build action (the ACL snippet action registered server-side).
+  // `parseAction` returns the resolved action params when allowed, or a falsy
+  // value when denied.
+  if (!parseAction || !parseAction(ACTIONS.build)) {
+    return null;
+  }
+
+  const title = itemConfig.title || t('Build Visualization Block');
+
+  return (
+    <>
+      <SchemaInitializerItem {...itemConfig} title={title} icon={<DashboardOutlined />} onClick={handleOpen} />
+      <Modal open={open} title={title} footer={null} destroyOnClose onCancel={handleClose} width={720}>
+        {/* TODO(task 9.2): the real BuildForm may own its own modal/drawer; if
+            so, move modal ownership into BuildForm and render it directly. The
+            onInsert/onClose contract stays the same. */}
+        <BuildForm onInsert={handleInsert} onClose={handleClose} />
+      </Modal>
+    </>
+  );
+};
+
+export default BuildVisualizationBlockInitializer;

package/src/client/PreviewPanel.tsx

@@ -0,0 +1,136 @@
+import React, { useMemo } from 'react';
+import { Alert, Button, Empty, Space, Spin, Typography } from 'antd';
+import { ISchema, SchemaComponent, SchemaComponentOptions } from '@nocobase/client';
+import { useT } from './locale';
+
+/**
+ * A single validator adjustment, mirroring the `ValidationAdjustment` shape
+ * produced by the server-side Spec Validator. Declared locally so the client
+ * never imports server pipeline code.
+ */
+export interface Adjustment {
+  /** The original field reference (or a short role descriptor). */
+  reference: string;
+  /** Whether the reference was dropped, remapped, or left an unmet role. */
+  action: 'removed' | 'remapped' | 'unmet-role';
+  /** The field the reference was remapped to (only set for `remapped`). */
+  replacement?: string;
+  /** A short, non-localized diagnostic describing the change. */
+  reason?: string;
+}
+
+export interface PreviewPanelProps {
+  /** The generated, validated block schema to preview. Absent while building. */
+  schema?: ISchema;
+  /** True when the result came from the fallback path (Req 9.5 / 12.4). */
+  usedFallback?: boolean;
+  /**
+   * The validator adjustments. Accepts the validated `Adjustment[]` shape; an
+   * `unknown` value (e.g. raw JSON from the build record) is tolerated and
+   * narrowed at render time.
+   */
+  adjustments?: Adjustment[] | unknown;
+  /** Insert the previewed schema into the page/popup (Req 9.2). */
+  onInsert: (schema: ISchema) => void;
+  /** Re-run generation, keeping the same inputs (Req 9.4 / 12.5). */
+  onRegenerate: () => void;
+  /** Dismiss the preview without inserting anything (Req 9.3). */
+  onCancel: () => void;
+  /** Whether a build/regenerate is in flight; disables actions + shows a spinner. */
+  loading?: boolean;
+}
+
+/** Type guard narrowing the loosely-typed `adjustments` prop to `Adjustment[]`. */
+function isAdjustmentArray(value: unknown): value is Adjustment[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (item): item is Adjustment =>
+        typeof item === 'object' &&
+        item !== null &&
+        typeof (item as Adjustment).reference === 'string' &&
+        typeof (item as Adjustment).action === 'string',
+    )
+  );
+}
+
+/** Render a one-line, human-readable description of a single adjustment. */
+function describeAdjustment(adjustment: Adjustment): string {
+  if (adjustment.action === 'remapped' && adjustment.replacement) {
+    return `${adjustment.reference} → ${adjustment.replacement}`;
+  }
+  return `${adjustment.reference} → ${adjustment.action}`;
+}
+
+/**
+ * Presentational preview surface for a generated block (Req 9.1–9.5, 12.4–12.5).
+ *
+ * It renders the generated `schema` read-only via {@link SchemaComponent},
+ * surfaces a fallback notice and any validator adjustments, and exposes
+ * Insert / Regenerate / Cancel actions. It owns no data or side effects — the
+ * parent `BuildForm` supplies the schema and wires the callbacks.
+ */
+export const PreviewPanel = (props: PreviewPanelProps) => {
+  const { schema, usedFallback, adjustments, onInsert, onRegenerate, onCancel, loading } = props;
+  const t = useT();
+
+  const adjustmentList = useMemo<Adjustment[]>(
+    () => (isAdjustmentArray(adjustments) ? adjustments : []),
+    [adjustments],
+  );
+
+  const hasSchema = Boolean(schema);
+
+  return (
+    <Space direction="vertical" style={{ width: '100%' }} size="middle">
+      {usedFallback ? <Alert type="warning" showIcon message={t('A fallback block was generated')} /> : null}
+
+      {adjustmentList.length > 0 ? (
+        <Alert
+          type="info"
+          showIcon
+          message={t('Some fields were adjusted to match the collection')}
+          description={
+            <ul style={{ margin: 0, paddingInlineStart: 20 }}>
+              {adjustmentList.map((adjustment, index) => (
+                <li key={`${adjustment.reference}-${adjustment.action}-${index}`}>{describeAdjustment(adjustment)}</li>
+              ))}
+            </ul>
+          }
+        />
+      ) : null}
+
+      <section aria-label={t('Preview')}>
+        <Typography.Title level={5} style={{ marginTop: 0 }}>
+          {t('Preview')}
+        </Typography.Title>
+        {hasSchema ? (
+          <SchemaComponentOptions>
+            <SchemaComponent schema={schema as ISchema} />
+          </SchemaComponentOptions>
+        ) : loading ? (
+          <Spin aria-label={t('Generating')} />
+        ) : (
+          <Empty image={Empty.PRESENTED_IMAGE_SIMPLE} description={t('Preview')} />
+        )}
+      </section>
+
+      <Space>
+        <Button
+          type="primary"
+          onClick={() => schema && onInsert(schema)}
+          disabled={!hasSchema || loading}
+          aria-label={t('Insert')}
+        >
+          {t('Insert')}
+        </Button>
+        <Button onClick={onRegenerate} loading={loading} aria-label={t('Regenerate')}>
+          {t('Regenerate')}
+        </Button>
+        <Button onClick={onCancel} disabled={loading} aria-label={t('Cancel')}>
+          {t('Cancel')}
+        </Button>
+      </Space>
+    </Space>
+  );
+};