@fastspace/schema-form 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,539 @@
+import { ControllerRenderProps } from 'react-hook-form';
+import { default as default_2 } from 'react';
+import { FieldValues } from 'react-hook-form';
+import { GridSize } from '@mui/material/Grid';
+import { JSX } from 'react/jsx-runtime';
+import { Path } from 'react-hook-form';
+import { ReactNode } from 'react';
+import { UseFormReturn } from 'react-hook-form';
+import * as v from 'valibot';
+
+/** 自动完成（支持多选、远程搜索、分页） */
+declare const AutocompleteWidget: WidgetComponent;
+export { AutocompleteWidget }
+export { AutocompleteWidget as SelectWidget }
+
+/**
+ * 根据 ParsedSchema 和当前值动态构建完整的 Valibot schema
+ */
+export declare function buildValibotSchema<T extends Record<string, unknown>>(parsed: ParsedSchema<T>, values: Record<string, unknown>): v.ObjectSchema<Record<string, v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>, undefined>;
+
+/** 复选框 */
+export declare const CheckboxWidget: WidgetComponent;
+
+/** 紧凑型表单字段样式 */
+export declare const compactFieldStyles: {
+    "& .MuiInputBase-input": {
+        fontSize: number;
+        padding: string;
+    };
+    "& .MuiInputLabel-root": {
+        fontSize: number;
+        transform: string;
+        "&.MuiInputLabel-shrink": {
+            transform: string;
+        };
+    };
+    "& .MuiOutlinedInput-root": {
+        minHeight: string;
+    };
+    "& .MuiFormHelperText-root": {
+        marginTop: string;
+        fontSize: number;
+    };
+    "& .MuiInputLabel-asterisk": {
+        display: string;
+    };
+};
+
+/** 支持的组件类型 */
+export declare type ComponentType = 'Text' | 'Number' | 'Password' | 'Textarea' | 'Select' | 'Autocomplete' | 'Checkbox' | 'Switch' | 'Radio' | 'Slider' | 'Rating' | 'Date' | 'Time' | 'DateTime' | 'Upload' | 'Hidden' | 'Custom' | 'Group' | 'FormList';
+
+/** 复合条件：支持逻辑运算 */
+export declare type CompoundCondition = {
+    and: ConditionExpression[];
+} | {
+    or: ConditionExpression[];
+} | {
+    not: ConditionExpression;
+};
+
+/**
+ * 计算所有字段的状态
+ */
+export declare function computeAllFieldStates<T extends Record<string, unknown>>(parsed: ParsedSchema<T>, values: Record<string, unknown>, globalDisabled?: boolean, globalReadOnly?: boolean): FieldStatesMap;
+
+/** 计算配置 */
+export declare type ComputeConfig = {
+    /** 表达式字符串，如 "price * quantity" */
+    expr: string;
+    /** 依赖字段（可选，自动从 expr 解析） */
+    dependencies?: string[];
+    /** 小数精度（可选，默认为不处理） */
+    precision?: number;
+    /** 舍入模式（可选，默认为 'round' 四舍五入） */
+    roundMode?: 'round' | 'ceil' | 'floor';
+};
+
+/**
+ * 计算单个字段的状态
+ */
+export declare function computeFieldState(field: FieldSchema, values: Record<string, unknown>, globalDisabled?: boolean, globalReadOnly?: boolean): FieldState;
+
+/** 条件表达式：简单或复合或函数 */
+export declare type ConditionExpression = SimpleCondition | CompoundCondition | ((values: Record<string, unknown>) => boolean);
+
+/**
+ * 创建动态 resolver（用于 react-hook-form）
+ */
+export declare function createDynamicResolver<T extends Record<string, unknown>>(parsed: ParsedSchema<T>): (values: Record<string, unknown>, _context: unknown, _options: unknown) => Promise<{
+    values: {
+        [x: string]: unknown;
+    };
+    errors: {};
+} | {
+    values: {};
+    errors: Record<string, {
+        type: string;
+        message: string;
+    }>;
+}>;
+
+/** 自定义组件 */
+export declare const CustomWidget: WidgetComponent;
+
+/** 日期格式 */
+export declare const DATE_FORMAT = "YYYY-MM-DD";
+
+export declare const DATETIME_FORMAT = "YYYY-MM-DD HH:mm";
+
+/** 日期时间选择 */
+export declare const DateTimeWidget: WidgetComponent;
+
+/** 日期选择 */
+export declare const DateWidget: WidgetComponent;
+
+/**
+ * 默认 Widget 映射表
+ */
+export declare const defaultWidgets: Record<string, WidgetComponent>;
+
+/**
+ * 求值条件表达式
+ * @param condition 条件表达式
+ * @param values 当前表单值
+ * @returns 条件是否满足
+ */
+export declare function evaluateCondition(condition: ConditionExpression, values: Record<string, unknown>): boolean;
+
+/**
+ * 从条件表达式中提取依赖字段
+ * @param condition 条件表达式
+ * @returns 依赖字段名数组
+ */
+export declare function extractDependencies(condition: ConditionExpression): string[];
+
+export declare const FieldRenderer: typeof FieldRendererInner;
+
+/**
+ * 字段渲染器组件
+ * 负责根据 Schema 渲染单个表单字段
+ */
+declare function FieldRendererInner<T extends FieldValues = FieldValues>({ field, index, values, form, disabled, readOnly, widgets, optionsMap, useGrid, }: FieldRendererProps<T>): JSX.Element | null;
+
+export declare interface FieldRendererProps<T extends FieldValues = FieldValues> {
+    /** 字段 Schema */
+    field: FieldSchema<T>;
+    /** 字段索引 */
+    index: number;
+    /** 当前表单值 */
+    values: Record<string, unknown>;
+    /** 表单方法 */
+    form: UseFormReturn<T>;
+    /** 全局禁用 */
+    disabled?: boolean;
+    /** 全局只读 */
+    readOnly?: boolean;
+    /** Widget 映射 */
+    widgets: Record<string, WidgetComponent>;
+    /** 选项映射 */
+    optionsMap: Record<string, OptionItem[]>;
+    /** 是否使用 Grid 包装 */
+    useGrid?: boolean;
+}
+
+/** 字段 Schema 定义 */
+export declare type FieldSchema<T extends FieldValues = FieldValues> = {
+    /** 字段名（对应表单数据的 key） */
+    name: Path<T>;
+    /** 组件类型 */
+    component: ComponentType | string;
+    /** 默认值 */
+    defaultValue?: unknown;
+    ui?: {
+        /** 标签 */
+        label?: string;
+        /** 占位符 */
+        placeholder?: string;
+        /** 帮助文本 */
+        helperText?: string;
+        /** 提示信息 */
+        tooltip?: string;
+        /** 选项（用于 Select/Radio 等） */
+        options?: OptionItem[];
+        /** 异步获取选项 */
+        optionRequest?: (values: T) => Promise<OptionItem[]>;
+        /** 远程搜索/分页配置 (Autocomplete 专用) */
+        remoteConfig?: RemoteConfig;
+        /** 组件透传属性 */
+        props?: Record<string, unknown>;
+    };
+    /** 列跨度（基于 MUI Grid），支持响应式 */
+    colSpan?: GridSize | {
+        xs?: GridSize;
+        sm?: GridSize;
+        md?: GridSize;
+        lg?: GridSize;
+        xl?: GridSize;
+    };
+    /** 强制从新行开始 */
+    newLine?: boolean;
+    /** 子字段定义 */
+    columns?: FieldSchema<T>[];
+    /** 最小行数 */
+    minItems?: number;
+    /** 最大行数 */
+    maxItems?: number;
+    /** 添加按钮文案 */
+    addText?: string;
+    /** 是否可拖拽排序 */
+    sortable?: boolean;
+    /** 是否可复制 */
+    copyable?: boolean;
+    /** 验证规则数组 */
+    rules?: ValidationRule[];
+    /** 条件显示 */
+    visibleWhen?: ConditionExpression;
+    /** 条件禁用 */
+    disabledWhen?: ConditionExpression;
+    /** 条件必填 */
+    requiredWhen?: ConditionExpression;
+    /** 只读 */
+    readonly?: boolean;
+    /** 禁用 */
+    disabled?: boolean;
+    /** 隐藏（不渲染） */
+    hidden?: boolean;
+    /** 自动计算配置 */
+    compute?: ComputeConfig;
+    /** 提交前转换 */
+    transform?: (value: unknown, values: T) => unknown;
+    /** 不参与提交 */
+    noSubmit?: boolean;
+    /** 依赖字段（用于触发重新计算/校验） */
+    dependencies?: string[];
+};
+
+/**
+ * 字段状态计算引擎
+ *
+ * 计算每个字段的运行时状态：
+ * - visible: 是否显示
+ * - disabled: 是否禁用
+ * - required: 是否必填
+ * - readonly: 是否只读
+ */
+/** 单个字段的运行时状态 */
+export declare type FieldState = {
+    /** 是否可见 */
+    visible: boolean;
+    /** 是否禁用 */
+    disabled: boolean;
+    /** 是否必填 */
+    required: boolean;
+    /** 是否只读 */
+    readonly: boolean;
+};
+
+/** 所有字段的状态映射 */
+export declare type FieldStatesMap = Map<string, FieldState>;
+
+/**
+ * FormList 动态列表组件
+ * 支持动态添加/删除/复制行
+ */
+export declare const FormListWidget: WidgetComponent;
+
+/**
+ * 获取字段的所有下游依赖（递归）
+ * 用于判断哪些字段需要重新计算
+ */
+export declare function getDownstreamFields(fieldName: string, dependencyGraph: Map<string, Set<string>>): Set<string>;
+
+/**
+ * 获取需要监听的依赖字段
+ * 用于构建 useWatch 的 name 数组
+ */
+export declare function getWatchFields<T extends Record<string, unknown>>(parsed: ParsedSchema<T>): string[];
+
+/**
+ * Grid 布局组件
+ * 使用 MUI Grid 实现响应式网格布局
+ */
+export declare const GridLayout: ({ spacing, children }: GridLayoutProps) => JSX.Element;
+
+export declare interface GridLayoutProps {
+    /** 间距 */
+    spacing?: number;
+    /** 子元素 */
+    children: ReactNode;
+}
+
+/**
+ * Group 分组组件
+ * 将多个字段组合在一行内显示
+ */
+export declare const GroupWidget: WidgetComponent;
+
+/** 隐藏字段 */
+export declare const HiddenWidget: WidgetComponent;
+
+export declare type LayoutConfig = {
+    /** 布局类型 */
+    type: 'grid' | 'stack';
+    /** 列数（仅 grid） */
+    columns?: number;
+    /** 区域定义（CSS Grid Area 风格） */
+    areas?: string[][];
+    /** 间距 */
+    spacing?: number;
+};
+
+/**
+ * 合并默认值与外部传入值
+ */
+export declare function mergeDefaultValues<T extends Record<string, unknown>>(parsed: ParsedSchema<T>, externalValues?: Partial<T>): Partial<T>;
+
+/** 数字输入 */
+export declare const NumberWidget: WidgetComponent;
+
+export declare type OptionItem = {
+    label: string;
+    value: string | number | boolean | null;
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+
+export declare type ParsedSchema<T extends FieldValues = FieldValues> = {
+    /** 原始输入 */
+    input: SchemaInput<T>;
+    /** 字段索引（name -> FieldSchema） */
+    fieldMap: Map<string, FieldSchema<T>>;
+    /** 依赖图（field -> dependents） */
+    dependencyGraph: Map<string, Set<string>>;
+    /** 默认值 */
+    defaultValues: Partial<T>;
+    /** 扁平化的所有字段列表 (包含嵌套字段) */
+    allFields: FieldSchema<T>[];
+};
+
+/**
+ * 解析 Schema，生成预处理后的结构
+ */
+export declare function parseSchema<T extends Record<string, unknown>>(input: SchemaInput<T>): ParsedSchema<T> & {
+    allFields: FieldSchema<T>[];
+};
+
+/** 密码输入 */
+export declare const PasswordWidget: WidgetComponent;
+
+/** 单选组 */
+export declare const RadioWidget: WidgetComponent;
+
+/** 评分 */
+export declare const RatingWidget: WidgetComponent;
+
+/** 远程加载配置 (分页/搜索) */
+declare type RemoteConfig = {
+    /** 获取数据的函数 */
+    fetchOptions: (keyword: string, page: number, pageSize: number) => Promise<{
+        data: OptionItem[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /** 每页条数 */
+    pageSize?: number;
+    /** 搜索防抖时间 (ms) */
+    debounceTimeout?: number;
+    /** 最小搜索字符数 */
+    minSearchLength?: number;
+    /** 加载状态回调 */
+    onLoadingChange?: (loading: boolean) => void;
+    /** 根据 ID 获取选项 (用于回显) */
+    fetchById?: (value: string | number) => Promise<OptionItem | null>;
+};
+
+/** 导出 SchemaForm 组件 */
+export declare const SchemaForm: <T extends FieldValues>(props: SchemaFormProps<T> & {
+    ref?: default_2.Ref<SchemaFormInstance<T>>;
+}) => default_2.ReactElement;
+
+export declare type SchemaFormInstance<T extends FieldValues = FieldValues> = UseFormReturn<T> & {
+    /** 提交表单 */
+    submit: () => Promise<void> | boolean;
+    /** 获取表单值（排除 noSubmit 字段） */
+    getFormValues: () => Partial<T>;
+    /** 批量设置值 */
+    setValues: (values: Partial<T>) => void;
+};
+
+declare type SchemaFormProps<T extends FieldValues = FieldValues> = {
+    /** Schema 定义 */
+    schema: SchemaInput<T>;
+    /** 默认值 */
+    defaultValues?: Partial<T>;
+    /** 提交回调 */
+    onSubmit?: (values: T) => void | Promise<void | boolean>;
+    /** 值变化回调 */
+    onValuesChange?: (values: T) => void;
+    /** 是否使用 Grid 布局 */
+    grid?: boolean;
+    /** 全局只读 */
+    readOnly?: boolean;
+    /** 全局禁用 */
+    disabled?: boolean;
+    /** 自定义控件 */
+    widgets?: Record<string, WidgetComponent<T>>;
+    /** 子元素 */
+    children?: React.ReactNode;
+    /** 间距 */
+    spacing?: number;
+};
+
+export declare type SchemaInput<T extends FieldValues = FieldValues> = {
+    /** 字段定义 */
+    fields: FieldSchema<T>[];
+    /** 布局配置（可选，默认使用 colSpan 响应式布局） */
+    layout?: LayoutConfig;
+};
+
+/** 简单条件：单字段比较 */
+export declare type SimpleCondition = {
+    field: string;
+    eq?: unknown;
+    ne?: unknown;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    in?: unknown[];
+    notIn?: unknown[];
+    empty?: boolean;
+    notEmpty?: boolean;
+};
+
+/** 滑块 */
+export declare const SliderWidget: WidgetComponent;
+
+/**
+ * Stack 布局组件
+ * 使用 MUI Stack 实现垂直堆叠布局
+ */
+export declare const StackLayout: ({ spacing, children }: StackLayoutProps) => JSX.Element;
+
+export declare interface StackLayoutProps {
+    /** 间距 */
+    spacing?: number;
+    /** 子元素 */
+    children: ReactNode;
+}
+
+/** 开关 */
+export declare const SwitchWidget: WidgetComponent;
+
+/** 多行文本 */
+export declare const TextareaWidget: WidgetComponent;
+
+/** 文本输入 */
+export declare const TextWidget: WidgetComponent;
+
+/** 时间选择 */
+export declare const TimeWidget: WidgetComponent;
+
+/** 基础验证规则 */
+export declare type ValidationRule = {
+    type: 'required';
+    message?: string;
+} | {
+    type: 'minLength';
+    value: number;
+    message?: string;
+} | {
+    type: 'maxLength';
+    value: number;
+    message?: string;
+} | {
+    type: 'min';
+    value: number;
+    message?: string;
+} | {
+    type: 'max';
+    value: number;
+    message?: string;
+} | {
+    type: 'pattern';
+    value: string | RegExp;
+    message?: string;
+} | {
+    type: 'email';
+    message?: string;
+} | {
+    type: 'url';
+    message?: string;
+} | {
+    type: 'custom';
+    validate: (value: unknown, values: unknown) => boolean | string;
+} | {
+    type: 'array';
+    minItems?: number;
+    maxItems?: number;
+    message?: string;
+};
+
+/** Widget 组件类型 */
+export declare type WidgetComponent<T extends FieldValues = FieldValues> = React.ComponentType<WidgetProps<T>>;
+
+export declare type WidgetProps<T extends FieldValues = FieldValues> = {
+    /** React Hook Form 字段对象 */
+    field: ControllerRenderProps<T>;
+    /** 标签 */
+    label?: string;
+    /** 是否有错误 */
+    error?: boolean;
+    /** 帮助/错误文本 */
+    helperText?: React.ReactNode;
+    /** 选项（用于 Select 等） */
+    options?: OptionItem[];
+    /** 透传属性 */
+    fieldProps?: Record<string, unknown> & {
+        disabled?: boolean;
+        required?: boolean;
+        readOnly?: boolean;
+    };
+    /** 表单实例 */
+    form?: UseFormReturn<T>;
+    /** 字段 Schema（用于 Group/FormList） */
+    schema?: FieldSchema<T>;
+    /** Widget 映射（用于嵌套渲染） */
+    widgets?: Record<string, WidgetComponent<T>>;
+    /** 选项映射（用于嵌套渲染） */
+    optionsMap?: Record<string, OptionItem[]>;
+    /** 全局禁用 */
+    globalDisabled?: boolean;
+    /** 全局只读 */
+    globalReadOnly?: boolean;
+    /** 当前表单值 (优化) */
+    values?: Record<string, unknown>;
+};
+
+export { }