plugin-build-visualization-block 0.1.1

package/src/client/SettingsPage.tsx

@@ -0,0 +1,138 @@
+import { createForm } from '@formily/core';
+import { Field, FormProvider } from '@formily/react';
+import { useAPIClient } from '@nocobase/client';
+import { Alert, App, Button, Card, Form, Space, Switch } from 'antd';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { CollectionMultiSelect, CollectionMultiSelectValue, LLMServiceSelect, ModelSelect } from './components';
+import { useT } from './locale';
+import { SETTINGS_COLLECTION_NAME } from '../shared/constants';
+
+interface SettingsValues {
+  defaultDataSource?: string | null;
+  defaultCollections?: string[];
+  defaultLLMService?: string | null;
+  defaultModel?: string | null;
+  enableAITool?: boolean;
+}
+
+function normalizeSettings(value: unknown): SettingsValues {
+  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,
+    enableAITool: source.enableAITool !== false,
+  };
+}
+
+function readStringValue(values: unknown, key: string): string | undefined {
+  if (!values || typeof values !== 'object') {
+    return undefined;
+  }
+  const value = (values as Record<string, unknown>)[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+export const SettingsPage: React.FC = () => {
+  const api = useAPIClient();
+  const { message } = App.useApp();
+  const t = useT();
+  const form = useMemo(() => createForm(), []);
+  const [collectionValue, setCollectionValue] = useState<CollectionMultiSelectValue>({ collections: [] });
+  const [enableAITool, setEnableAITool] = useState(true);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [loadFailed, setLoadFailed] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+
+    const loadSettings = async () => {
+      setLoading(true);
+      setLoadFailed(false);
+      try {
+        const response = await api.resource(SETTINGS_COLLECTION_NAME).publicGet();
+        if (!active) {
+          return;
+        }
+        const settings = normalizeSettings((response as { data?: { data?: unknown } }).data?.data);
+        setCollectionValue({
+          dataSource: settings.defaultDataSource ?? undefined,
+          collections: settings.defaultCollections ?? [],
+        });
+        form.setValues({
+          llmService: settings.defaultLLMService,
+          model: settings.defaultModel,
+        });
+        setEnableAITool(settings.enableAITool !== false);
+      } catch (error) {
+        if (!active) {
+          return;
+        }
+        console.error('[plugin-build-visualization-block] Failed to load settings:', error);
+        setLoadFailed(true);
+      } finally {
+        if (active) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadSettings();
+    return () => {
+      active = false;
+    };
+  }, [api, form]);
+
+  const handleSave = useCallback(async () => {
+    setSaving(true);
+    try {
+      await api.resource(SETTINGS_COLLECTION_NAME).update({
+        filterByTk: 1,
+        values: {
+          defaultDataSource: collectionValue.dataSource,
+          defaultCollections: collectionValue.collections ?? [],
+          defaultLLMService: readStringValue(form.values, 'llmService'),
+          defaultModel: readStringValue(form.values, 'model'),
+          enableAITool,
+        },
+      });
+      message.success(t('Saved successfully'));
+    } finally {
+      setSaving(false);
+    }
+  }, [api, collectionValue, enableAITool, form, message, t]);
+
+  return (
+    <Card loading={loading}>
+      <Space direction="vertical" size="middle" style={{ width: '100%', maxWidth: 720 }}>
+        {loadFailed ? <Alert type="error" showIcon message={t('Failed to load the list')} /> : null}
+        <Form layout="vertical">
+          <Form.Item label={t('Default collections')}>
+            <CollectionMultiSelect value={collectionValue} onChange={setCollectionValue} />
+          </Form.Item>
+          <FormProvider form={form}>
+            <Form.Item label={t('Default AI service')}>
+              <Field name="llmService" component={[LLMServiceSelect, { style: { width: '100%' } }]} />
+            </Form.Item>
+            <Form.Item label={t('Default model')}>
+              <Field name="model" component={[ModelSelect, { style: { width: '100%' } }]} />
+            </Form.Item>
+          </FormProvider>
+          <Form.Item label={t('Enable AI tool')}>
+            <Switch checked={enableAITool} onChange={setEnableAITool} />
+          </Form.Item>
+          <Button type="primary" loading={saving} onClick={handleSave}>
+            {t('Save')}
+          </Button>
+        </Form>
+      </Space>
+    </Card>
+  );
+};
+
+export default SettingsPage;

package/src/client/components/BuildPhaseTag.tsx

@@ -0,0 +1,62 @@
+import React from 'react';
+import { Tag } from 'antd';
+import { useField } from '@formily/react';
+import { isField } from '@formily/core';
+import { BuildPhase } from '../../shared/constants';
+import { useT } from '../locale';
+
+/** Ant Design Tag colors for each build phase. */
+const PHASE_COLORS: Record<BuildPhase, string> = {
+  idle: 'default',
+  queued: 'default',
+  analyzing: 'processing',
+  generating: 'processing',
+  completed: 'success',
+  failed: 'error',
+};
+
+/** Localization keys for each build phase label. */
+const PHASE_LABELS: Record<BuildPhase, string> = {
+  idle: 'Idle',
+  queued: 'Queued',
+  analyzing: 'Analyzing',
+  generating: 'Generating',
+  completed: 'Completed',
+  failed: 'Failed',
+};
+
+const PHASES = Object.keys(PHASE_COLORS) as BuildPhase[];
+
+function isBuildPhase(value: unknown): value is BuildPhase {
+  return typeof value === 'string' && (PHASES as string[]).includes(value);
+}
+
+export interface BuildPhaseTagProps {
+  /**
+   * The phase to render. When omitted, the value is read from the surrounding
+   * Formily field, allowing the tag to be used as a read-pretty field
+   * component as well as a plain presentational tag.
+   */
+  value?: BuildPhase;
+}
+
+/**
+ * A small Ant Design `Tag` that renders a build phase with a phase-specific
+ * color and a localized label.
+ */
+export const BuildPhaseTag = (props: BuildPhaseTagProps) => {
+  const t = useT();
+  const field = useField();
+  const fieldValue = isField(field) ? field.value : undefined;
+  const phase = props.value ?? fieldValue;
+
+  if (!isBuildPhase(phase)) {
+    return null;
+  }
+
+  return (
+    <Tag color={PHASE_COLORS[phase]} aria-label={t(PHASE_LABELS[phase])}>
+      {t(PHASE_LABELS[phase])}
+    </Tag>
+  );
+};

package/src/client/components/CollectionMultiSelect.tsx

@@ -0,0 +1,124 @@
+import React, { useCallback, useMemo } from 'react';
+import { Select, Space, Typography } from 'antd';
+import { useACLRoleContext, useCompile, useDataSourceManager, DEFAULT_DATA_SOURCE_KEY } from '@nocobase/client';
+import { MAX_COLLECTIONS } from '../../shared/constants';
+import { useT } from '../locale';
+
+interface SelectOption {
+  label: string;
+  value: string;
+}
+
+/**
+ * The combined value managed by {@link CollectionMultiSelect}: the chosen data
+ * source key plus the selected collection names within it.
+ */
+export interface CollectionMultiSelectValue {
+  dataSource?: string;
+  collections?: string[];
+}
+
+export interface CollectionMultiSelectProps {
+  /** Current value (supplied by Formily's field decorator or a parent). */
+  value?: CollectionMultiSelectValue;
+  /** Change handler (supplied by Formily's field decorator or a parent). */
+  onChange?: (value: CollectionMultiSelectValue) => void;
+  disabled?: boolean;
+}
+
+/**
+ * Two linked selects: a data source picker (Req 1.1) and a multiple-collection
+ * picker scoped to the chosen data source. The collection list is filtered to
+ * collections the current user can `list` (Req 1.2, 1.5), and the selection is
+ * capped at {@link MAX_COLLECTIONS}. Changing the data source clears the
+ * previously selected collections.
+ */
+export const CollectionMultiSelect = (props: CollectionMultiSelectProps) => {
+  const { value, onChange, disabled } = props;
+  const t = useT();
+  const compile = useCompile();
+  const dataSourceManager = useDataSourceManager();
+  const { parseAction } = useACLRoleContext();
+
+  const dataSourceKey = value?.dataSource;
+  const selectedCollections = value?.collections ?? [];
+
+  const dataSourceOptions = useMemo<SelectOption[]>(() => {
+    const dataSources = dataSourceManager?.getDataSources() ?? [];
+    return dataSources.map((dataSource) => ({
+      label: compile(dataSource.displayName) || dataSource.key,
+      value: dataSource.key,
+    }));
+  }, [dataSourceManager, compile]);
+
+  const canList = useCallback(
+    (collectionName: string) => Boolean(parseAction(`${collectionName}:list`)),
+    [parseAction],
+  );
+
+  const collectionOptions = useMemo<SelectOption[]>(() => {
+    if (!dataSourceKey) {
+      return [];
+    }
+    const dataSource = dataSourceManager?.getDataSource(dataSourceKey);
+    const collections = dataSource?.collectionManager?.getCollections() ?? [];
+    return collections
+      .filter((collection) => canList(collection.name))
+      .map((collection) => ({
+        label: compile(collection.title) || collection.name,
+        value: collection.name,
+      }));
+  }, [dataSourceManager, dataSourceKey, compile, canList]);
+
+  const handleDataSourceChange = useCallback(
+    (nextDataSource: string) => {
+      // Switching data source invalidates any previously selected collections.
+      onChange?.({ dataSource: nextDataSource, collections: [] });
+    },
+    [onChange],
+  );
+
+  const handleCollectionsChange = useCallback(
+    (nextCollections: string[]) => {
+      // Enforce the upper bound (Req 1.3) regardless of how many were picked.
+      const capped = nextCollections.slice(0, MAX_COLLECTIONS);
+      onChange?.({ dataSource: dataSourceKey, collections: capped });
+    },
+    [onChange, dataSourceKey],
+  );
+
+  const atLimit = selectedCollections.length >= MAX_COLLECTIONS;
+
+  return (
+    <Space direction="vertical" style={{ width: '100%' }} size="small">
+      <Select<string>
+        aria-label={t('Data source')}
+        placeholder={t('Data source')}
+        style={{ width: '100%' }}
+        options={dataSourceOptions}
+        value={dataSourceKey ?? (dataSourceOptions.length ? undefined : DEFAULT_DATA_SOURCE_KEY)}
+        onChange={handleDataSourceChange}
+        disabled={disabled}
+        showSearch
+        optionFilterProp="label"
+      />
+      <Select<string[]>
+        aria-label={t('Collections')}
+        placeholder={t('Collections')}
+        style={{ width: '100%' }}
+        mode="multiple"
+        options={collectionOptions}
+        value={selectedCollections}
+        onChange={handleCollectionsChange}
+        disabled={disabled || !dataSourceKey}
+        showSearch
+        optionFilterProp="label"
+      />
+      {atLimit ? (
+        <Typography.Text type="warning">
+          {t('You can select at most {{max}} collections', { max: MAX_COLLECTIONS })}
+        </Typography.Text>
+      ) : null}
+    </Space>
+  );
+};

package/src/client/components/LLMServiceSelect.tsx

@@ -0,0 +1,108 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import { useAPIClient } from '@nocobase/client';
+import { Select, SelectProps } from 'antd';
+import { useField } from '@formily/react';
+import { Field, isField } from '@formily/core';
+import { useT } from '../locale';
+
+interface SelectOption {
+  label: string;
+  value: string;
+}
+
+/**
+ * Shape of a single LLM service record returned by `ai:listLLMServices`.
+ * Only the fields this component relies on are declared; everything else is
+ * ignored.
+ */
+interface LLMServiceRecord {
+  name?: string;
+  title?: string;
+}
+
+/**
+ * Pull the `{ data: { data: [...] } }` list payload out of an API response
+ * without resorting to `any`. Unknown shapes degrade to an empty list.
+ */
+function normalizeRecords(response: unknown): LLMServiceRecord[] {
+  const data = (response as { data?: { data?: unknown } } | undefined)?.data?.data;
+  return Array.isArray(data) ? (data as LLMServiceRecord[]) : [];
+}
+
+export type LLMServiceSelectProps = Omit<SelectProps<string>, 'options' | 'loading' | 'value' | 'onChange'>;
+
+/**
+ * Formily-aware Select that loads the available LLM services from the AI
+ * plugin (`ai:listLLMServices`). Selecting a service clears the sibling
+ * `model` field so a stale model is never submitted with a new service.
+ *
+ * - Req 4.1: loads services from `api.resource('ai').listLLMServices()`.
+ * - Req 4.5: surfaces a load failure as an error state (empty option list +
+ *   a status message) rather than throwing.
+ * - Req 4.6: clears the sibling `model` field on change.
+ */
+export const LLMServiceSelect = (props: LLMServiceSelectProps) => {
+  const t = useT();
+  const api = useAPIClient();
+  const field = useField<Field>();
+  const [options, setOptions] = useState<SelectOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [hasError, setHasError] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+    const loadServices = async () => {
+      setLoading(true);
+      setHasError(false);
+      try {
+        const res: unknown = await api.resource('ai').listLLMServices();
+        if (!active) return;
+        const next = normalizeRecords(res)
+          .filter((item): item is LLMServiceRecord & { name: string } => Boolean(item.name))
+          .map<SelectOption>((item) => ({
+            label: item.title || item.name,
+            value: item.name,
+          }));
+        setOptions(next);
+      } catch (err: unknown) {
+        if (!active) return;
+        console.error('Failed to load LLM services:', err);
+        setOptions([]);
+        setHasError(true);
+      } finally {
+        if (active) setLoading(false);
+      }
+    };
+    loadServices();
+    return () => {
+      active = false;
+    };
+  }, [api]);
+
+  const handleChange = useCallback(
+    (value: string) => {
+      field.setValue(value);
+      // Reset the sibling model field whenever the service changes (Req 4.6).
+      const sibling = field.query('.model').take();
+      if (isField(sibling)) {
+        sibling.setValue(undefined);
+      }
+    },
+    [field],
+  );
+
+  return (
+    <Select<string>
+      {...props}
+      options={options}
+      loading={loading}
+      status={hasError ? 'error' : undefined}
+      value={field.value}
+      onChange={handleChange}
+      notFoundContent={hasError ? t('Failed to load the list') : undefined}
+      allowClear
+      showSearch
+      optionFilterProp="label"
+    />
+  );
+};

package/src/client/components/ModelSelect.tsx

@@ -0,0 +1,105 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import { useAPIClient } from '@nocobase/client';
+import { Select, SelectProps } from 'antd';
+import { useField, useForm, observer } from '@formily/react';
+import { Field } from '@formily/core';
+import { useT } from '../locale';
+
+interface SelectOption {
+  label: string;
+  value: string;
+}
+
+/**
+ * Shape of a single model record returned by `ai:listModels`. Providers vary
+ * on whether they return `id` or `name`, so both are optional and handled.
+ */
+interface ModelRecord {
+  id?: string;
+  name?: string;
+}
+
+function normalizeRecords(response: unknown): ModelRecord[] {
+  const data = (response as { data?: { data?: unknown } } | undefined)?.data?.data;
+  return Array.isArray(data) ? (data as ModelRecord[]) : [];
+}
+
+export type ModelSelectProps = Omit<SelectProps<string>, 'options' | 'loading' | 'value' | 'onChange' | 'disabled'>;
+
+/**
+ * Formily-aware Select that lists the models available for the currently
+ * selected LLM service. It observes `form.values.llmService` and:
+ *
+ * - Req 4.2: loads models via `api.resource('ai').listModels({ llmService })`.
+ * - stays disabled until a service is selected.
+ * - clears its own value and options when the service changes, so a model
+ *   from a previous service is never left selected.
+ * - Req 4.5: surfaces a load failure as an error state instead of throwing.
+ */
+export const ModelSelect = observer((props: ModelSelectProps) => {
+  const t = useT();
+  const api = useAPIClient();
+  const field = useField<Field>();
+  const form = useForm();
+  const [options, setOptions] = useState<SelectOption[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [hasError, setHasError] = useState(false);
+
+  const llmService = typeof form.values?.llmService === 'string' ? form.values.llmService : undefined;
+
+  useEffect(() => {
+    let active = true;
+    if (!llmService) {
+      setOptions([]);
+      setHasError(false);
+      return;
+    }
+    const loadModels = async () => {
+      setLoading(true);
+      setHasError(false);
+      try {
+        const res: unknown = await api.resource('ai').listModels({ llmService });
+        if (!active) return;
+        const next = normalizeRecords(res)
+          .map((item) => item.id || item.name)
+          .filter((value): value is string => Boolean(value))
+          .map<SelectOption>((value) => ({ label: value, value }));
+        setOptions(next);
+      } catch (err: unknown) {
+        if (!active) return;
+        console.error('Failed to load models:', err);
+        setOptions([]);
+        setHasError(true);
+      } finally {
+        if (active) setLoading(false);
+      }
+    };
+    loadModels();
+    return () => {
+      active = false;
+    };
+  }, [api, llmService]);
+
+  const handleChange = useCallback(
+    (value: string) => {
+      field.setValue(value);
+    },
+    [field],
+  );
+
+  return (
+    <Select<string>
+      {...props}
+      options={options}
+      loading={loading}
+      status={hasError ? 'error' : undefined}
+      value={field.value}
+      onChange={handleChange}
+      disabled={!llmService}
+      notFoundContent={hasError ? t('Failed to load the list') : undefined}
+      allowClear
+      showSearch
+      optionFilterProp="label"
+    />
+  );
+});

package/src/client/components/index.ts

@@ -0,0 +1,8 @@
+export { LLMServiceSelect } from './LLMServiceSelect';
+export type { LLMServiceSelectProps } from './LLMServiceSelect';
+export { ModelSelect } from './ModelSelect';
+export type { ModelSelectProps } from './ModelSelect';
+export { CollectionMultiSelect } from './CollectionMultiSelect';
+export type { CollectionMultiSelectProps, CollectionMultiSelectValue } from './CollectionMultiSelect';
+export { BuildPhaseTag } from './BuildPhaseTag';
+export type { BuildPhaseTagProps } from './BuildPhaseTag';