@digitalsee-ai/rcs 0.0.14

package/dist/components/dynamic-form/types/events.d.ts

@@ -0,0 +1,203 @@
+import { FormInstance } from 'antd';
+import { ConditionNode } from './form-schema';
+/**
+ * 事件类型
+ */
+export type EventType = 'fieldChange' | 'fieldBlur' | 'fieldFocus' | 'formMount' | 'custom';
+/**
+ * 事件触发器配置
+ */
+export type EventTrigger = {
+    type: 'fieldChange' | 'fieldBlur' | 'fieldFocus';
+    field: string;
+} | {
+    type: 'formMount';
+} | {
+    type: 'custom';
+    eventName: string;
+};
+/**
+ * 动作定义 - 清空字段
+ */
+export interface ClearFieldsAction {
+    type: 'clearFields';
+    /** 要清空的字段名列表 */
+    targets: string[];
+}
+/**
+ * 动作定义 - 设置字段值
+ */
+export interface SetFieldValueAction {
+    type: 'setFieldValue';
+    /** 目标字段名 */
+    target: string;
+    /** 静态值（直接设置） */
+    value?: unknown;
+    /** 动态值路径（从 payload 或 formValues 中提取）
+     * 例如：'payload.data.userName' 或 'formValues.department'
+     */
+    valueFrom?: string;
+}
+/**
+ * 动作定义 - 设置字段禁用状态
+ */
+export interface SetFieldDisabledAction {
+    type: 'setFieldDisabled';
+    /** 目标字段名 */
+    target: string;
+    /** 是否禁用 */
+    disabled: boolean;
+}
+/**
+ * 动作定义 - 触发字段验证
+ */
+export interface TriggerValidationAction {
+    type: 'triggerValidation';
+    /** 要验证的字段名列表，为空则验证所有字段 */
+    targets?: string[];
+}
+/**
+ * 动作定义 - 调用数据加载器
+ * 用于自定义组件场景：调用接口获取数据后设置给其他字段
+ */
+export interface CallDataLoaderAction {
+    type: 'callDataLoader';
+    /** 数据加载器的 action 名称 */
+    action: string;
+    /** 传递给数据加载器的参数 */
+    params?: Record<string, unknown>;
+    /** 将结果设置到哪个字段（可选） */
+    resultTo?: string;
+}
+/**
+ * 动作定义 - 自定义动作
+ * 通过自定义处理函数实现复杂逻辑
+ */
+export interface CustomAction {
+    type: 'custom';
+    /** 自定义处理函数的标识符 */
+    handler: string;
+    /** 传递给处理函数的参数 */
+    params?: Record<string, unknown>;
+}
+/**
+ * 动作联合类型
+ */
+export type Action = ClearFieldsAction | SetFieldValueAction | SetFieldDisabledAction | TriggerValidationAction | CallDataLoaderAction | CustomAction;
+/**
+ * 事件配置
+ */
+export interface EventConfig {
+    /** 事件 ID（可选，用于调试和日志） */
+    id?: string;
+    /** 事件触发器 */
+    trigger: EventTrigger;
+    /** 触发条件（可选，复用现有条件系统） */
+    conditions?: ConditionNode;
+    /** 要执行的动作列表 */
+    actions: Action[];
+    /** 防抖时间（毫秒，可选） */
+    debounce?: number;
+}
+/**
+ * 事件载荷
+ * 包含事件触发时的上下文信息
+ */
+export interface EventPayload {
+    /** 事件类型 */
+    type: EventType;
+    /** 触发事件的字段名（fieldChange/fieldBlur/fieldFocus） */
+    field?: string;
+    /** 自定义事件名（custom 类型） */
+    eventName?: string;
+    /** 字段的旧值（fieldChange） */
+    oldValue?: unknown;
+    /** 字段的新值（fieldChange） */
+    newValue?: unknown;
+    /** 自定义数据（custom 类型） */
+    payload?: Record<string, unknown>;
+    /** 触发时间戳 */
+    timestamp: number;
+}
+/**
+ * 动作执行上下文
+ * 提供给动作执行器的上下文信息
+ */
+export interface ActionContext {
+    /** Ant Design Form 实例 */
+    form: FormInstance;
+    /** 当前表单所有值 */
+    formValues: Record<string, unknown>;
+    /** 触发事件的载荷 */
+    eventPayload: EventPayload;
+    /** 数据加载器（可选） */
+    optionsLoader?: (action: string, params: Record<string, unknown>, ctx: unknown) => Promise<unknown>;
+    /** 自定义动作处理器映射表（可选） */
+    customHandlers?: Record<string, (context: ActionContext, params?: Record<string, unknown>) => void | Promise<void>>;
+    /** 执行深度（用于防止无限循环） */
+    executionDepth?: number;
+}
+/**
+ * 事件分发函数类型
+ * 供自定义组件调用以触发自定义事件
+ */
+export type DispatchEventFn = (eventName: string, payload?: Record<string, unknown>) => void;
+/**
+ * EventEngine 配置
+ */
+export interface EventEngineConfig {
+    /** 事件配置列表 */
+    events: EventConfig[];
+    /** 最大执行深度（防止无限循环，默认 10） */
+    maxExecutionDepth?: number;
+    /** 是否启用调试日志（默认 false） */
+    debug?: boolean;
+}
+/**
+ * 字段事件处理器接口
+ * 提供给字段组件的统一事件触发接口
+ *
+ * 设计目的：
+ * - 将所有字段级别的事件触发函数聚合到一个对象中
+ * - 便于扩展新的事件类型，无需修改多处传参代码
+ * - 字段组件通过 context.eventHandlers 访问
+ *
+ * @example
+ * // 在字段组件中使用
+ * const handleBlur = () => {
+ *   context.eventHandlers?.onBlur(field.name)
+ * }
+ */
+export interface FieldEventHandlers {
+    /**
+     * 字段失焦事件
+     * @param fieldPath - 字段路径
+     */
+    onBlur: (fieldPath: string) => void;
+    /**
+     * 字段聚焦事件
+     * @param fieldPath - 字段路径
+     */
+    onFocus: (fieldPath: string) => void;
+    /**
+     * 自定义事件分发
+     * @param eventName - 事件名称
+     * @param payload - 事件载荷
+     */
+    dispatch: DispatchEventFn;
+}
+/**
+ * EventEngine Hook 返回值类型
+ */
+export interface EventEngineReturn {
+    /**
+     * 触发字段值变化事件
+     * 由 DynamicForm 在 onValuesChange 中调用
+     */
+    triggerFieldChange: (fieldPath: string, newValue: unknown, oldValue?: unknown) => void;
+    /**
+     * 字段事件处理器
+     * 传递给字段组件使用
+     */
+    fieldEventHandlers: FieldEventHandlers;
+}

package/dist/components/dynamic-form/types/field-component.d.ts

@@ -0,0 +1,156 @@
+import { DynamicFormField, FieldDef, Option } from './form-schema';
+import { FieldEventHandlers } from './events';
+import type * as React from 'react';
+/**
+ * Options 加载器函数类型
+ * 用于动态加载 Select/Cascader 等组件的选项
+ */
+export type OptionsLoader = (action: string, params: Record<string, unknown>, ctx: {
+    values: Record<string, unknown>;
+}) => Promise<Option[]>;
+/**
+ * 变量信息类型
+ */
+export interface VariableInfo {
+    path: string;
+    label?: string;
+    type?: string;
+}
+/**
+ * 字段渲染上下文
+ * 提供字段渲染所需的所有外部信息
+ */
+export interface FieldRenderContext {
+    /** 表单当前值（用于条件判断） */
+    values: Record<string, unknown>;
+    /** 动态 Options 加载器 */
+    optionsLoader?: OptionsLoader;
+    /** 变量验证函数 */
+    validateVariable?: (variable: string) => boolean | Promise<boolean>;
+    /** 节点 ID（workflow 场景） */
+    nodeId?: string;
+    /** MCP 模式（启用 AI 填充） */
+    mcpMode?: boolean;
+    /** 可用变量列表 */
+    availableVariables?: VariableInfo[];
+    /** 字段事件处理器（统一的事件触发接口） */
+    eventHandlers?: FieldEventHandlers;
+}
+/**
+ * 字段组件 Props
+ * 所有字段组件都接收这个统一的 Props 接口
+ *
+ * 注意：这些组件会被 Form.Item 包裹，Form.Item 会通过 cloneElement 注入以下 props：
+ * - value: 表单字段的当前值
+ * - onChange: 值变化回调
+ * - id: 字段 ID
+ *
+ * 字段组件必须接收这些 props 并转发给内部的 Ant Design 组件
+ */
+export interface FieldComponentProps<T extends FieldDef = FieldDef> {
+    /** 字段定义 */
+    field: T;
+    /** 是否禁用 */
+    disabled: boolean;
+    /** 是否只读 */
+    readOnly: boolean;
+    /** 渲染上下文 */
+    context: FieldRenderContext;
+    /** 表单字段值（由 Form.Item 注入） */
+    value?: unknown;
+    /** 值变化回调（由 Form.Item 注入） */
+    onChange?: (value: unknown) => void;
+    /** 字段 ID（由 Form.Item 注入） */
+    id?: string;
+}
+/**
+ * 字段组件元数据
+ * 描述组件的能力和特性，用于 FieldRenderer 决定如何包装组件
+ */
+export interface FieldComponentMeta {
+    /**
+     * 组件内部是否已处理 variableInsert 特性
+     * 如果为 true，FieldRenderer 不会额外包装 ValueModeWrapper
+     */
+    supportsVariableInsert?: boolean;
+    /**
+     * 组件内部是否已处理 aiFillable 特性
+     * 如果为 true，FieldRenderer 不会额外包装 AIFieldWrapper
+     */
+    supportsAiFillable?: boolean;
+    /**
+     * 是否需要 Form.Item 的 name 属性绑定
+     * 默认为 true
+     * 复杂字段（如 ARRAY）内部自行处理 name，外层 Form.Item 不需要 name
+     */
+    needsFormItemName?: boolean;
+    /**
+     * 自定义 valuePropName
+     * 例如 CHECKBOX/SWITCH 使用 "checked"
+     */
+    valuePropName?: string;
+    /**
+     * 是否为复杂字段
+     * 复杂字段（ARRAY/OBJECT/KEY_VALUE/ARRAY_OBJECT）的外层 Form.Item 仅用于 label 显示
+     */
+    isComplexField?: boolean;
+    /**
+     * 是否为纯展示字段
+     * 展示字段（DIVIDER/INFO_CARD）不需要 Form.Item 包装
+     */
+    isDisplayOnly?: boolean;
+}
+/**
+ * 字段组件定义
+ * 组合组件和元数据
+ */
+export interface FieldComponentDefinition<T extends FieldDef = FieldDef> {
+    /** React 组件 */
+    component: React.ComponentType<FieldComponentProps<T>>;
+    /** 组件元数据 */
+    meta: FieldComponentMeta;
+}
+/**
+ * 字段注册选项
+ */
+export interface RegisterFieldOptions {
+    /** 是否覆盖已存在的注册 */
+    override?: boolean;
+}
+/**
+ * 字段注册表接口
+ */
+export interface IFieldRegistry {
+    /**
+     * 注册字段组件
+     * @param type - 字段类型标识
+     * @param definition - 组件定义（包含组件和元数据）
+     * @param options - 注册选项
+     */
+    register(type: DynamicFormField | string, definition: FieldComponentDefinition, options?: RegisterFieldOptions): void;
+    /**
+     * 注销字段组件
+     * @param type - 要注销的字段类型
+     */
+    unregister(type: DynamicFormField | string): void;
+    /**
+     * 获取已注册的字段组件
+     * @param type - 字段类型
+     * @returns 组件定义或 undefined
+     */
+    get(type: DynamicFormField | string): FieldComponentDefinition | undefined;
+    /**
+     * 检查字段类型是否已注册
+     * @param type - 字段类型
+     */
+    has(type: DynamicFormField | string): boolean;
+    /**
+     * 获取所有已注册的字段类型
+     */
+    getRegisteredTypes(): Array<DynamicFormField | string>;
+    /**
+     * 克隆注册表
+     * 用于创建作用域隔离的注册表实例
+     */
+    clone(): IFieldRegistry;
+}

package/dist/components/dynamic-form/types/form-schema.d.ts

@@ -0,0 +1,297 @@
+import { ValidationRule } from './validation';
+import { EventConfig } from './events';
+export type Option = {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+    children?: Option[];
+};
+export type ValueMode = 'string' | 'jsExpr' | 'code' | 'variable';
+export type OptionsSource = {
+    kind: 'static';
+    items: Option[];
+} | {
+    kind: 'dynamic' | 'async';
+    deps?: string[];
+    action: string;
+    params?: Record<string, unknown>;
+    fallbackOptions?: Option[];
+};
+export type OperatorType = 'EQ' | 'NOT' | 'GT' | 'LT' | 'GE' | 'LE' | 'ISEVEN' | 'ISODD' | 'IC' | 'NIC' | 'IN' | 'NIN' | 'EXISTS' | 'EMPTY' | 'NOT_EMPTY';
+export type ConditionNode = {
+    AND?: ConditionNode[];
+    OR?: ConditionNode[];
+    key?: string;
+    keyword?: OperatorType;
+    value?: unknown;
+} | undefined;
+export type HideStrategy = 'unregister' | 'keepValue';
+export type VisibleWhen = {
+    deps?: string[];
+    conditions?: ConditionNode;
+    clearOnHide?: boolean;
+    hideStrategy?: HideStrategy;
+} | undefined;
+export declare enum DynamicFormField {
+    TEXT = "TEXT",// antd Input
+    TEXTAREA = "TEXTAREA",// antd Input.TextArea
+    NUMBER = "NUMBER",// antd InputNumber
+    PASSWORD = "PASSWORD",// antd Input.Password
+    SELECT = "SELECT",// antd Select
+    MULTI_SELECT = "MULTI_SELECT",// antd Select mode="multiple"
+    RADIO = "RADIO",// antd Radio.Group
+    CHECKBOX = "CHECKBOX",// antd Checkbox
+    CHECKBOX_GROUP = "CHECKBOX_GROUP",// antd Checkbox.Group
+    SWITCH = "SWITCH",// antd Switch
+    CASCADER = "CASCADER",// antd Cascader
+    TREE_SELECT = "TREE_SELECT",// antd TreeSelect
+    DATE = "DATE",// antd DatePicker
+    DATE_RANGE = "DATE_RANGE",// antd DatePicker.RangePicker
+    TIME = "TIME",// antd TimePicker
+    TIME_RANGE = "TIME_RANGE",// antd TimePicker.RangePicker
+    DATETIME = "DATETIME",// antd DatePicker showTime
+    UPLOAD = "UPLOAD",// antd Upload
+    RATE = "RATE",// antd Rate
+    SLIDER = "SLIDER",// antd Slider
+    COLOR_PICKER = "COLOR_PICKER",// antd ColorPicker
+    MENTIONS = "MENTIONS",// antd Mentions
+    AUTO_COMPLETE = "AUTO_COMPLETE",// antd AutoComplete
+    LABEL = "LABEL",// 纯文本展示
+    HIDDEN = "HIDDEN",// 隐藏字段
+    JSON = "JSON",// JSON 编辑器
+    DIVIDER = "DIVIDER",// 分割线
+    INFO_CARD = "INFO_CARD",// 展示卡片
+    ARRAY = "ARRAY",// 简单数组
+    OBJECT = "OBJECT",// 对象编辑器
+    KEY_VALUE = "KEY_VALUE",// 键值对编辑器
+    ARRAY_OBJECT = "ARRAY_OBJECT"
+}
+/** 基础字段定义 */
+export type BaseField = {
+    type: DynamicFormField;
+    name: string;
+    label?: string;
+    description?: string;
+    placeholder?: string;
+    defaultValue?: unknown;
+    valueMode?: ValueMode;
+    helpText?: string;
+    readOnly?: boolean | ConditionNode;
+    aiFillable?: boolean;
+    variableInsert?: boolean;
+    disabled?: boolean | ConditionNode;
+    required?: boolean | ConditionNode;
+    visibleWhen?: VisibleWhen;
+    rules?: ValidationRule[];
+    validateTrigger?: 'onChange' | 'onBlur' | 'onSubmit' | Array<'onChange' | 'onBlur' | 'onSubmit'>;
+    tooltip?: string;
+    extra?: string;
+    colon?: boolean;
+    labelCol?: {
+        span?: number;
+        offset?: number;
+    };
+    wrapperCol?: {
+        span?: number;
+        offset?: number;
+    };
+};
+/** Textarea 字段扩展 */
+export type TextareaField = BaseField & {
+    type: DynamicFormField.TEXTAREA;
+    minRows?: number;
+    maxRows?: number;
+    autoSize?: boolean | {
+        minRows?: number;
+        maxRows?: number;
+    };
+    showCount?: boolean;
+    maxLength?: number;
+};
+/** Select 字段扩展 */
+export type SelectField = BaseField & {
+    type: DynamicFormField.SELECT | DynamicFormField.MULTI_SELECT;
+    options?: Option[];
+    optionsSource?: OptionsSource;
+    showSearch?: boolean;
+    allowClear?: boolean;
+    mode?: 'multiple' | 'tags';
+    remoteSearch?: boolean;
+    searchDebounce?: number;
+    maxTagCount?: number;
+};
+/** Radio 字段扩展 */
+export type RadioField = BaseField & {
+    type: DynamicFormField.RADIO;
+    options: Option[];
+    optionType?: 'default' | 'button';
+    buttonStyle?: 'outline' | 'solid';
+};
+/** Checkbox Group 字段扩展 */
+export type CheckboxGroupField = BaseField & {
+    type: DynamicFormField.CHECKBOX_GROUP;
+    options: Option[];
+};
+/** Date 字段扩展 */
+export type DateField = BaseField & {
+    type: DynamicFormField.DATE | DynamicFormField.DATETIME;
+    picker?: 'date' | 'week' | 'month' | 'quarter' | 'year';
+    showTime?: boolean | object;
+    format?: string;
+    outputFormat?: 'timestamp' | 'string';
+    disabledDate?: string;
+    presets?: Array<{
+        label: string;
+        value: string;
+    }>;
+};
+/** DateRange 字段扩展 */
+export type DateRangeField = BaseField & {
+    type: DynamicFormField.DATE_RANGE;
+    picker?: 'date' | 'week' | 'month' | 'quarter' | 'year';
+    showTime?: boolean | object;
+    format?: string;
+};
+/** Time 字段扩展 */
+export type TimeField = BaseField & {
+    type: DynamicFormField.TIME;
+    format?: string;
+};
+/** Switch 字段扩展 */
+export type SwitchField = BaseField & {
+    type: DynamicFormField.SWITCH;
+    checkedChildren?: string;
+    unCheckedChildren?: string;
+    checkedValue?: unknown;
+    uncheckedValue?: unknown;
+};
+/** TimeRange 字段扩展 */
+export type TimeRangeField = BaseField & {
+    type: DynamicFormField.TIME_RANGE;
+    format?: string;
+};
+/** Number 字段扩展 */
+export type NumberField = BaseField & {
+    type: DynamicFormField.NUMBER;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    addonBefore?: string;
+    addonAfter?: string;
+    showThousandsSeparator?: boolean;
+    controls?: boolean;
+};
+/** Upload 字段扩展 */
+export type UploadField = BaseField & {
+    type: DynamicFormField.UPLOAD;
+    accept?: string;
+    maxCount?: number;
+    maxSize?: number;
+    listType?: 'text' | 'picture' | 'picture-card' | 'picture-circle';
+    action?: string;
+    multiple?: boolean;
+};
+/** Slider 字段扩展 */
+export type SliderField = BaseField & {
+    type: DynamicFormField.SLIDER;
+    min?: number;
+    max?: number;
+    step?: number;
+    marks?: Record<number, string>;
+    range?: boolean;
+};
+/** Rate 字段扩展 */
+export type RateField = BaseField & {
+    type: DynamicFormField.RATE;
+    count?: number;
+    allowHalf?: boolean;
+};
+/** Cascader 字段扩展 */
+export type CascaderField = BaseField & {
+    type: DynamicFormField.CASCADER;
+    options: Option[];
+    changeOnSelect?: boolean;
+    multiple?: boolean;
+    showSearch?: boolean;
+};
+/** TreeSelect 字段扩展 */
+export type TreeSelectField = BaseField & {
+    type: DynamicFormField.TREE_SELECT;
+    options: Option[];
+    multiple?: boolean;
+    showSearch?: boolean;
+    allowClear?: boolean;
+    treeCheckable?: boolean;
+};
+/** AutoComplete 字段扩展 */
+export type AutoCompleteField = BaseField & {
+    type: DynamicFormField.AUTO_COMPLETE;
+    options: Option[];
+    allowClear?: boolean;
+};
+/** 展示卡片 */
+export type InfoCardField = BaseField & {
+    type: DynamicFormField.INFO_CARD;
+    status?: 'info' | 'success' | 'warning' | 'error';
+    closable?: boolean;
+    showIcon?: boolean;
+};
+/** 数组字段定义 */
+export type ArrayField = BaseField & {
+    type: DynamicFormField.ARRAY;
+    itemSchema: FieldDef;
+    minItems?: number;
+    maxItems?: number;
+    allowCopy?: boolean;
+    itemLabel?: string;
+};
+/** 对象字段定义 */
+export type ObjectField = BaseField & {
+    type: DynamicFormField.OBJECT;
+    properties: Record<string, FieldDef>;
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+};
+/** 键值对字段定义 */
+export type KeyValueField = BaseField & {
+    type: DynamicFormField.KEY_VALUE;
+    keyPlaceholder?: string;
+    valuePlaceholder?: string;
+    maxDepth?: number;
+    minItems?: number;
+    maxItems?: number;
+};
+/** 对象数组字段定义 */
+export type ArrayObjectField = BaseField & {
+    type: DynamicFormField.ARRAY_OBJECT;
+    columns: FieldDef[];
+    rowCollapsible?: boolean;
+    allowCopy?: boolean;
+    minItems?: number;
+    maxItems?: number;
+};
+/** 字段定义联合类型 */
+export type FieldDef = BaseField | TextareaField | SelectField | RadioField | CheckboxGroupField | DateField | DateRangeField | TimeField | TimeRangeField | NumberField | UploadField | SliderField | RateField | CascaderField | TreeSelectField | AutoCompleteField | SwitchField | InfoCardField | ArrayField | ObjectField | KeyValueField | ArrayObjectField;
+/** 表单 Schema */
+export type FormSchema = {
+    fields: FieldDef[];
+    layout?: 'horizontal' | 'vertical' | 'inline';
+    labelCol?: {
+        span?: number;
+        offset?: number;
+    };
+    wrapperCol?: {
+        span?: number;
+        offset?: number;
+    };
+    colon?: boolean;
+    size?: 'small' | 'middle' | 'large';
+    pruneInvisibleOnSubmit?: boolean;
+    /** 事件配置列表 */
+    events?: EventConfig[];
+    /** 是否启用自动事件生成（默认 true）
+     * 当设置为 true 时，会根据字段的 optionsSource.deps 自动生成 clearFields 事件
+     */
+    enableAutoEvents?: boolean;
+};

package/dist/components/dynamic-form/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './field-component';
+export * from './form-schema';
+export * from './validation';
+export * from './events';