@tdesign-react/chat 1.0.2-alpha.9 → 1.1.0-alpha.2

package/es/chat-engine/components/json-render/catalog.d.ts

@@ -0,0 +1,614 @@
+/**
+ * TDesign Catalog 定义（约束层）
+ * 用于定义组件 props schema 和 actions 白名单
+ *
+ * 概念区分：
+ * - Catalog（本文件）：约束层，定义组件 props 的 Zod schemas 和 actions 白名单（给 AI/服务端用）
+ * - ComponentRegistry（catalog/index.ts）：渲染层，映射组件名到 React 组件（给 Renderer 用）
+ */
+import { z } from 'zod';
+/**
+ * TDesign 内置组件 Catalog
+ * 定义所有内置组件的 props schema 和可用 actions
+ *
+ * 这个 Catalog 用于：
+ * 1. 告诉 AI/LLM 可以生成哪些组件
+ * 2. 约束每个组件的 props 类型
+ * 3. 定义可触发的 actions 白名单
+ */
+export declare const tdesignCatalog: import("@json-render/core").Catalog<{
+    Button: {
+        props: z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            children: z.ZodOptional<z.ZodString>;
+            variant: z.ZodNullable<z.ZodEnum<["base", "outline", "dashed", "text"]>>;
+            theme: z.ZodNullable<z.ZodEnum<["default", "primary", "success", "warning", "danger"]>>;
+            size: z.ZodNullable<z.ZodEnum<["small", "medium", "large"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            loading: z.ZodNullable<z.ZodBoolean>;
+            block: z.ZodNullable<z.ZodBoolean>;
+            action: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+            }, "strip", z.ZodTypeAny, {
+                name?: string;
+                params?: Record<string, any>;
+            }, {
+                name?: string;
+                params?: Record<string, any>;
+            }>]>>;
+        }, "strip", z.ZodTypeAny, {
+            label?: string;
+            children?: string;
+            action?: string | {
+                name?: string;
+                params?: Record<string, any>;
+            };
+            block?: boolean;
+            loading?: boolean;
+            size?: "small" | "large" | "medium";
+            disabled?: boolean;
+            theme?: "default" | "danger" | "primary" | "warning" | "success";
+            variant?: "base" | "text" | "dashed" | "outline";
+        }, {
+            label?: string;
+            children?: string;
+            action?: string | {
+                name?: string;
+                params?: Record<string, any>;
+            };
+            block?: boolean;
+            loading?: boolean;
+            size?: "small" | "large" | "medium";
+            disabled?: boolean;
+            theme?: "default" | "danger" | "primary" | "warning" | "success";
+            variant?: "base" | "text" | "dashed" | "outline";
+        }>;
+        description: string;
+    };
+    Input: {
+        props: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            placeholder: z.ZodNullable<z.ZodString>;
+            type: z.ZodNullable<z.ZodEnum<["text", "password", "number"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            clearable: z.ZodNullable<z.ZodBoolean>;
+            maxlength: z.ZodNullable<z.ZodNumber>;
+            showLimitNumber: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            value?: string;
+            type?: "number" | "text" | "password";
+            disabled?: boolean;
+            placeholder?: string;
+            maxlength?: number;
+            clearable?: boolean;
+            showLimitNumber?: boolean;
+        }, {
+            value?: string;
+            type?: "number" | "text" | "password";
+            disabled?: boolean;
+            placeholder?: string;
+            maxlength?: number;
+            clearable?: boolean;
+            showLimitNumber?: boolean;
+        }>;
+        description: string;
+    };
+    TextField: {
+        props: z.ZodObject<{
+            label: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            valuePath: z.ZodString;
+            placeholder: z.ZodNullable<z.ZodString>;
+            required: z.ZodNullable<z.ZodBoolean>;
+            type: z.ZodNullable<z.ZodEnum<["text", "password", "email", "number", "tel"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            helperText: z.ZodNullable<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            label?: string;
+            name?: string;
+            type?: "number" | "text" | "tel" | "email" | "password";
+            valuePath?: string;
+            disabled?: boolean;
+            placeholder?: string;
+            required?: boolean;
+            helperText?: string;
+        }, {
+            label?: string;
+            name?: string;
+            type?: "number" | "text" | "tel" | "email" | "password";
+            valuePath?: string;
+            disabled?: boolean;
+            placeholder?: string;
+            required?: boolean;
+            helperText?: string;
+        }>;
+        description: string;
+    };
+    Text: {
+        props: z.ZodObject<{
+            content: z.ZodString;
+            variant: z.ZodNullable<z.ZodEnum<["body", "caption", "label"]>>;
+            color: z.ZodNullable<z.ZodEnum<["default", "primary", "secondary", "success", "warning", "error"]>>;
+            weight: z.ZodNullable<z.ZodEnum<["normal", "medium", "bold"]>>;
+        }, "strip", z.ZodTypeAny, {
+            content?: string;
+            weight?: "bold" | "normal" | "medium";
+            color?: "error" | "default" | "primary" | "warning" | "success" | "secondary";
+            variant?: "body" | "caption" | "label";
+        }, {
+            content?: string;
+            weight?: "bold" | "normal" | "medium";
+            color?: "error" | "default" | "primary" | "warning" | "success" | "secondary";
+            variant?: "body" | "caption" | "label";
+        }>;
+        description: string;
+    };
+    Card: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            bordered: z.ZodNullable<z.ZodBoolean>;
+            shadow: z.ZodNullable<z.ZodBoolean>;
+            loading: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            title?: string;
+            description?: string;
+            loading?: boolean;
+            bordered?: boolean;
+            shadow?: boolean;
+        }, {
+            title?: string;
+            description?: string;
+            loading?: boolean;
+            bordered?: boolean;
+            shadow?: boolean;
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Row: {
+        props: z.ZodObject<{
+            gutter: z.ZodNullable<z.ZodNumber>;
+            justify: z.ZodNullable<z.ZodEnum<["start", "end", "center", "space-around", "space-between"]>>;
+            align: z.ZodNullable<z.ZodEnum<["top", "middle", "bottom"]>>;
+        }, "strip", z.ZodTypeAny, {
+            gutter?: number;
+            justify?: "center" | "start" | "end" | "space-around" | "space-between";
+            align?: "top" | "bottom" | "middle";
+        }, {
+            gutter?: number;
+            justify?: "center" | "start" | "end" | "space-around" | "space-between";
+            align?: "top" | "bottom" | "middle";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Col: {
+        props: z.ZodObject<{
+            span: z.ZodNullable<z.ZodNumber>;
+            offset: z.ZodNullable<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            span?: number;
+            offset?: number;
+        }, {
+            span?: number;
+            offset?: number;
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Space: {
+        props: z.ZodObject<{
+            direction: z.ZodNullable<z.ZodEnum<["horizontal", "vertical"]>>;
+            size: z.ZodNullable<z.ZodUnion<[z.ZodEnum<["small", "medium", "large"]>, z.ZodNumber, z.ZodString]>>;
+            align: z.ZodNullable<z.ZodEnum<["start", "center", "end", "baseline"]>>;
+        }, "strip", z.ZodTypeAny, {
+            size?: string | number;
+            direction?: "vertical" | "horizontal";
+            align?: "center" | "start" | "end" | "baseline";
+        }, {
+            size?: string | number;
+            direction?: "vertical" | "horizontal";
+            align?: "center" | "start" | "end" | "baseline";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Column: {
+        props: z.ZodObject<{
+            gap: z.ZodNullable<z.ZodNumber>;
+            align: z.ZodNullable<z.ZodEnum<["start", "center", "end", "stretch"]>>;
+        }, "strip", z.ZodTypeAny, {
+            gap?: number;
+            align?: "center" | "start" | "end" | "stretch";
+        }, {
+            gap?: number;
+            align?: "center" | "start" | "end" | "stretch";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Divider: {
+        props: z.ZodObject<{
+            layout: z.ZodNullable<z.ZodEnum<["horizontal", "vertical"]>>;
+            dashed: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            layout?: "vertical" | "horizontal";
+            dashed?: boolean;
+        }, {
+            layout?: "vertical" | "horizontal";
+            dashed?: boolean;
+        }>;
+        description: string;
+    };
+}, {
+    submit: {
+        description: string;
+    };
+    reset: {
+        description: string;
+    };
+    cancel: {
+        description: string;
+    };
+}, Record<string, import("@json-render/core").ValidationFunction>>;
+/**
+ * 创建自定义 Catalog（扩展 TDesign 内置 Catalog）
+ *
+ * @param customConfig - 自定义 Catalog 配置
+ * @returns 合并后的 Catalog
+ *
+ * @example
+ * ```typescript
+ * import { createCustomCatalog } from '@tdesign-react/chat';
+ * import { z } from 'zod';
+ *
+ * const customCatalog = createCustomCatalog({
+ *   name: 'my-dashboard',
+ *   components: {
+ *     StatusCard: {
+ *       props: z.object({
+ *         title: z.string(),
+ *         status: z.enum(['success', 'warning', 'error', 'info']),
+ *         description: z.string().nullable(),
+ *       }),
+ *       description: 'Custom status card component',
+ *     },
+ *     ProgressBar: {
+ *       props: z.object({
+ *         label: z.string().nullable(),
+ *         percentage: z.number().min(0).max(100),
+ *         showInfo: z.boolean().nullable(),
+ *       }),
+ *       description: 'Custom progress bar component',
+ *     },
+ *   },
+ *   actions: {
+ *     refresh: { description: 'Refresh data' },
+ *     export: { description: 'Export to file' },
+ *   },
+ * });
+ *
+ * // 使用自定义 Catalog
+ * // 1. 在服务端：告诉 AI 可以生成哪些组件
+ * // 2. 在前端：配合 createCustomRegistry 提供渲染能力
+ * ```
+ */
+export declare function createCustomCatalog(customConfig: {
+    name: string;
+    components?: Record<string, any>;
+    actions?: Record<string, {
+        description: string;
+    }>;
+    validation?: 'strict' | 'warn';
+}): import("@json-render/core").Catalog<{
+    Button: {
+        props: z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            children: z.ZodOptional<z.ZodString>;
+            variant: z.ZodNullable<z.ZodEnum<["base", "outline", "dashed", "text"]>>;
+            theme: z.ZodNullable<z.ZodEnum<["default", "primary", "success", "warning", "danger"]>>;
+            size: z.ZodNullable<z.ZodEnum<["small", "medium", "large"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            loading: z.ZodNullable<z.ZodBoolean>;
+            block: z.ZodNullable<z.ZodBoolean>;
+            action: z.ZodNullable<z.ZodUnion<[z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+            }, "strip", z.ZodTypeAny, {
+                name?: string;
+                params?: Record<string, any>;
+            }, {
+                name?: string;
+                params?: Record<string, any>;
+            }>]>>;
+        }, "strip", z.ZodTypeAny, {
+            label?: string;
+            children?: string;
+            action?: string | {
+                name?: string;
+                params?: Record<string, any>;
+            };
+            block?: boolean;
+            loading?: boolean;
+            size?: "small" | "large" | "medium";
+            disabled?: boolean;
+            theme?: "default" | "danger" | "primary" | "warning" | "success";
+            variant?: "base" | "text" | "dashed" | "outline";
+        }, {
+            label?: string;
+            children?: string;
+            action?: string | {
+                name?: string;
+                params?: Record<string, any>;
+            };
+            block?: boolean;
+            loading?: boolean;
+            size?: "small" | "large" | "medium";
+            disabled?: boolean;
+            theme?: "default" | "danger" | "primary" | "warning" | "success";
+            variant?: "base" | "text" | "dashed" | "outline";
+        }>;
+        description: string;
+    };
+    Input: {
+        props: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            placeholder: z.ZodNullable<z.ZodString>;
+            type: z.ZodNullable<z.ZodEnum<["text", "password", "number"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            clearable: z.ZodNullable<z.ZodBoolean>;
+            maxlength: z.ZodNullable<z.ZodNumber>;
+            showLimitNumber: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            value?: string;
+            type?: "number" | "text" | "password";
+            disabled?: boolean;
+            placeholder?: string;
+            maxlength?: number;
+            clearable?: boolean;
+            showLimitNumber?: boolean;
+        }, {
+            value?: string;
+            type?: "number" | "text" | "password";
+            disabled?: boolean;
+            placeholder?: string;
+            maxlength?: number;
+            clearable?: boolean;
+            showLimitNumber?: boolean;
+        }>;
+        description: string;
+    };
+    TextField: {
+        props: z.ZodObject<{
+            label: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+            valuePath: z.ZodString;
+            placeholder: z.ZodNullable<z.ZodString>;
+            required: z.ZodNullable<z.ZodBoolean>;
+            type: z.ZodNullable<z.ZodEnum<["text", "password", "email", "number", "tel"]>>;
+            disabled: z.ZodNullable<z.ZodBoolean>;
+            helperText: z.ZodNullable<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            label?: string;
+            name?: string;
+            type?: "number" | "text" | "tel" | "email" | "password";
+            valuePath?: string;
+            disabled?: boolean;
+            placeholder?: string;
+            required?: boolean;
+            helperText?: string;
+        }, {
+            label?: string;
+            name?: string;
+            type?: "number" | "text" | "tel" | "email" | "password";
+            valuePath?: string;
+            disabled?: boolean;
+            placeholder?: string;
+            required?: boolean;
+            helperText?: string;
+        }>;
+        description: string;
+    };
+    Text: {
+        props: z.ZodObject<{
+            content: z.ZodString;
+            variant: z.ZodNullable<z.ZodEnum<["body", "caption", "label"]>>;
+            color: z.ZodNullable<z.ZodEnum<["default", "primary", "secondary", "success", "warning", "error"]>>;
+            weight: z.ZodNullable<z.ZodEnum<["normal", "medium", "bold"]>>;
+        }, "strip", z.ZodTypeAny, {
+            content?: string;
+            weight?: "bold" | "normal" | "medium";
+            color?: "error" | "default" | "primary" | "warning" | "success" | "secondary";
+            variant?: "body" | "caption" | "label";
+        }, {
+            content?: string;
+            weight?: "bold" | "normal" | "medium";
+            color?: "error" | "default" | "primary" | "warning" | "success" | "secondary";
+            variant?: "body" | "caption" | "label";
+        }>;
+        description: string;
+    };
+    Card: {
+        props: z.ZodObject<{
+            title: z.ZodNullable<z.ZodString>;
+            description: z.ZodNullable<z.ZodString>;
+            bordered: z.ZodNullable<z.ZodBoolean>;
+            shadow: z.ZodNullable<z.ZodBoolean>;
+            loading: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            title?: string;
+            description?: string;
+            loading?: boolean;
+            bordered?: boolean;
+            shadow?: boolean;
+        }, {
+            title?: string;
+            description?: string;
+            loading?: boolean;
+            bordered?: boolean;
+            shadow?: boolean;
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Row: {
+        props: z.ZodObject<{
+            gutter: z.ZodNullable<z.ZodNumber>;
+            justify: z.ZodNullable<z.ZodEnum<["start", "end", "center", "space-around", "space-between"]>>;
+            align: z.ZodNullable<z.ZodEnum<["top", "middle", "bottom"]>>;
+        }, "strip", z.ZodTypeAny, {
+            gutter?: number;
+            justify?: "center" | "start" | "end" | "space-around" | "space-between";
+            align?: "top" | "bottom" | "middle";
+        }, {
+            gutter?: number;
+            justify?: "center" | "start" | "end" | "space-around" | "space-between";
+            align?: "top" | "bottom" | "middle";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Col: {
+        props: z.ZodObject<{
+            span: z.ZodNullable<z.ZodNumber>;
+            offset: z.ZodNullable<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            span?: number;
+            offset?: number;
+        }, {
+            span?: number;
+            offset?: number;
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Space: {
+        props: z.ZodObject<{
+            direction: z.ZodNullable<z.ZodEnum<["horizontal", "vertical"]>>;
+            size: z.ZodNullable<z.ZodUnion<[z.ZodEnum<["small", "medium", "large"]>, z.ZodNumber, z.ZodString]>>;
+            align: z.ZodNullable<z.ZodEnum<["start", "center", "end", "baseline"]>>;
+        }, "strip", z.ZodTypeAny, {
+            size?: string | number;
+            direction?: "vertical" | "horizontal";
+            align?: "center" | "start" | "end" | "baseline";
+        }, {
+            size?: string | number;
+            direction?: "vertical" | "horizontal";
+            align?: "center" | "start" | "end" | "baseline";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Column: {
+        props: z.ZodObject<{
+            gap: z.ZodNullable<z.ZodNumber>;
+            align: z.ZodNullable<z.ZodEnum<["start", "center", "end", "stretch"]>>;
+        }, "strip", z.ZodTypeAny, {
+            gap?: number;
+            align?: "center" | "start" | "end" | "stretch";
+        }, {
+            gap?: number;
+            align?: "center" | "start" | "end" | "stretch";
+        }>;
+        hasChildren: true;
+        description: string;
+    };
+    Divider: {
+        props: z.ZodObject<{
+            layout: z.ZodNullable<z.ZodEnum<["horizontal", "vertical"]>>;
+            dashed: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            layout?: "vertical" | "horizontal";
+            dashed?: boolean;
+        }, {
+            layout?: "vertical" | "horizontal";
+            dashed?: boolean;
+        }>;
+        description: string;
+    };
+}, {
+    submit: {
+        description: string;
+    };
+    reset: {
+        description: string;
+    };
+    cancel: {
+        description: string;
+    };
+}, Record<string, import("@json-render/core").ValidationFunction>>;
+/**
+ * 导出 TDesign Catalog 的组件列表（给 AI prompt 用）
+ */
+export declare const tdesignComponentList: string[];
+/**
+ * 导出 TDesign Catalog 的 actions 列表（给 AI prompt 用）
+ */
+export declare const tdesignActionList: string[];
+/**
+ * Prompt 模板模式
+ * - 'default': 默认模板，生成标准的 JSON Schema UI
+ * - 'a2ui': A2UI 模板，使用 A2UI 特定的消息格式和协议
+ * - 'custom': 自定义模板，完全由 customTemplate 参数控制
+ */
+export type PromptTemplateMode = 'default' | 'a2ui' | 'custom';
+/**
+ * 组件文档定义类型
+ * props 支持两种格式：
+ * 1. Record<string, string> - 人可读的 props 描述，如 { label: 'string - Button text' }
+ * 2. ZodObject - Zod schema 对象，会自动转换为描述
+ */
+export interface ComponentDoc {
+    description: string;
+    /** Props 定义：可以是字符串描述映射，也可以是 Zod schema */
+    props: Record<string, string> | z.ZodObject<any>;
+    hasChildren?: boolean;
+}
+/**
+ * 内部使用的标准化组件文档类型（props 已转为字符串）
+ */
+export interface NormalizedComponentDoc {
+    description: string;
+    props: Record<string, string>;
+    hasChildren?: boolean;
+}
+/**
+ * 自定义模板生成器函数类型
+ * 接收标准化后的组件文档（props 已转为字符串描述）
+ */
+export type CustomTemplateGenerator = (context: {
+    name: string;
+    components: Record<string, NormalizedComponentDoc>;
+    actions: Record<string, {
+        description: string;
+    }>;
+}) => string;
+/**
+ * 生成增强版 Catalog Prompt（包含完整 Props 文档和 Schema 示例）
+ *
+ * @param options - 配置选项
+ * @returns 详细的 AI Prompt 字符串
+ */
+export declare function generateCatalogPrompt(options?: {
+    name?: string;
+    components?: Record<string, ComponentDoc>;
+    actions?: Record<string, {
+        description: string;
+    }>;
+    /** 是否包含 Schema 示例 */
+    includeExample?: boolean;
+    /**
+     * Prompt 模板模式
+     * - 'default': 标准 JSON Schema UI 模板
+     * - 'a2ui': A2UI 协议模板（需服务端配合）
+     * - 'custom': 使用自定义模板生成器
+     */
+    templateMode?: PromptTemplateMode;
+    /**
+     * 自定义模板生成器（仅当 templateMode='custom' 时使用）
+     * 接收组件和 actions 上下文，返回完整的 prompt 字符串
+     */
+    customTemplate?: CustomTemplateGenerator;
+}): string;