@fastspace/schema-form 0.0.15 → 2.0.0

package/dist/index.d.ts

@@ -1,377 +1,1087 @@
-import { ControllerRenderProps } from 'react-hook-form';
+/**
+ * Next-Gen Schema Form (V4)
+ *
+ * 基于 TanStack Form 的声明式表单引擎
+ *
+ * @packageDocumentation
+ */
+
+import { CheckboxProps } from '@mui/material';
 import { default as default_2 } from 'react';
-import { FieldValues } from 'react-hook-form';
-import { GridSize } from '@mui/material/Grid';
+import { FC } from 'react';
+import { FormApi } from '@tanstack/react-form';
+import { FormHTMLAttributes } from 'react';
 import { JSX } from 'react/jsx-runtime';
-import { Path } from 'react-hook-form';
+import { JSXElementConstructor } from 'react';
+import { NamedExoticComponent } from 'react';
+import { RadioProps } from '@mui/material';
+import { ReactElement } from 'react';
 import { ReactNode } from 'react';
-import { UseFormReturn } from 'react-hook-form';
+import { ReactPortal } from 'react';
+import { SwitchProps } from '@mui/material';
+import { SxProps } from '@mui/material';
+import { TextFieldProps } from '@mui/material';
+import { Theme } from '@mui/material';
 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 type AnalysisResult = {
+    /** 反向依赖索引: Dep -> Rules */
+    dependencyMap: Map<string, SchemaRule[]>;
+    /** 拓扑排序序列 */
+    topologicalOrder: string[];
+    /** 所有检测到的循环 */
+    cycles: string[][];
+    /** 孤立字段 */
+    isolatedFields: string[];
+    /** 静态分析报告 */
+    report: StaticAnalysisReport;
+};
 
-/** 复选框 */
-export declare const CheckboxWidget: WidgetComponent;
+declare type AnyFormApi = FormApi<any, any, any, any, any, any, any, any, any, any, any, any>;
 
-/** 紧凑型表单字段样式 */
-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;
+declare type AnyFormApi_2 = FormApi<any, any, any, any, any, any, any, any, any, any, any, any>;
+
+declare type AnyFormApi_3 = any;
+
+declare type AnyFormApi_4 = any;
+
+/**
+ * 异步选项配置（带依赖）
+ */
+export declare type AsyncOptionsConfig = {
+    /** 异步获取选项的函数 */
+    fetcher: (scope: EvalScope, signal?: AbortSignal) => Promise<any[]>;
+    /**
+     * 依赖的字段列表，当这些字段值变化时重新加载选项
+     * @example deps: ['province'] - 当 province 变化时重新加载
+     */
+    deps: string[];
+};
+
+/**
+ * 异步任务调度器 (V4 Enhanced)
+ * 负责处理 Options 请求、异步计算等
+ *
+ * 特性:
+ * - Race Control: AbortController + VersionHash
+ * - Stable Hash: 基于内容的稳定哈希
+ * - 缓存管理: LRU 策略
+ * - 请求去重: 相同 hash 的请求复用
+ */
+export declare class AsyncScheduler {
+    private cache;
+    private activeRequests;
+    private pendingPromises;
+    private config;
+    constructor(config?: AsyncSchedulerConfig);
+    /**
+     * 执行异步任务
+     * @param target 目标字段 (用于取消互斥请求)
+     * @param hash 版本哈希 (deps hash)
+     * @param fetcher 异步函数
+     * @param scope 执行作用域
+     * @returns Promise<any>
+     */
+    schedule(target: string, hash: string, fetcher: (scope: EvalScope, signal: AbortSignal) => Promise<any>, scope: EvalScope): Promise<any>;
+    /**
+     * 设置缓存 (带 LRU 策略)
+     */
+    private setCache;
+    /**
+     * 生成稳定的依赖哈希
+     * 使用排序后的 JSON 确保相同内容生成相同 hash
+     */
+    generateHash(deps: Record<string, any>): string;
+    /**
+     * 稳定的 JSON 序列化 (对象键排序)
+     */
+    private stableStringify;
+    /**
+     * 取消指定目标的请求
+     */
+    cancel(target: string): void;
+    /**
+     * 取消所有请求
+     */
+    cancelAll(): void;
+    /**
+     * 清除缓存
+     */
+    clearCache(target?: string): void;
+    /**
+     * 获取缓存统计
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        keys: string[];
     };
+    /**
+     * 使缓存条目失效
+     */
+    invalidate(target: string, hash?: string): void;
+}
+
+/**
+ * AsyncScheduler 配置
+ */
+export declare type AsyncSchedulerConfig = {
+    /** 缓存过期时间 (ms)，默认 5 分钟 */
+    staleTime?: number;
+    /** 最大缓存条目数 */
+    maxCacheSize?: number;
+    /** 请求超时时间 (ms)，默认 30 秒 */
+    timeout?: number;
+    /** 是否启用请求去重 (同 hash 的请求只发一次) */
+    deduplication?: boolean;
 };
 
-/** 支持的组件类型 */
-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 const AutocompleteWidget: default_2.FC<AutocompleteWidgetProps>;
 
-/** 复合条件：支持逻辑运算 */
-export declare type CompoundCondition = {
-    and: ConditionExpression[];
-} | {
-    or: ConditionExpression[];
-} | {
-    not: ConditionExpression;
+export declare type AutocompleteWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<AutocompleteWidgetRenderProps, keyof WidgetProps>;
+
+export declare const AutocompleteWidgetRender: default_2.NamedExoticComponent<AutocompleteWidgetRenderProps>;
+
+export declare type AutocompleteWidgetRenderProps = WidgetProps & {
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    multiple?: boolean;
+    freeSolo?: boolean;
+    loading?: boolean;
+    /** 远程搜索配置 */
+    remoteConfig?: RemoteConfig;
+    /** 指定选项显示文本的字段，默认 "label" */
+    optionLabelProp?: string;
+    /** 指定选项绑定值的字段，默认 "value" */
+    optionValueProp?: string;
+    /** 无数据时下拉面板提示文本 */
+    emptyText?: string;
+    /** 是否显示添加按钮（函数式控制或布尔值） */
+    showAddSuffix?: boolean | SuffixButtonRender;
+    /** 是否显示清空按钮 */
+    clearable?: boolean;
+    /** Suffix 按钮渲染函数 */
+    suffixButton?: SuffixButtonRender;
+    /** 添加选项成功回调 */
+    onAddOptionSuccess?: OnAddOptionSuccess;
+    /** 添加新选项后自动选中，默认 false */
+    autoSelectNewOption?: boolean;
+    /** 每次展开时刷新数据，默认 false (仅首次加载) */
+    refreshOnOpen?: boolean;
+    /** 搜索清空配置 */
+    searchClearConfig?: SearchClearConfig;
 };
 
+/** Suffix 按钮配置 (替代下拉箭头位置) */
+declare type ButtonConfig = {
+    /**
+     * 按钮图标内容 (默认 AddIcon)
+     * 注意：MUI 会自动用 IconButton 包裹，所以这里只传图标/文本内容，不要传 Button 组件
+     * 例如：<AddIcon /> 或 <Typography>新增</Typography>
+     */
+    icon?: default_2.ReactNode;
+    /** 点击回调 */
+    onClick: () => void;
+    /** 按钮提示 (tooltip) */
+    tooltip?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+};
+
+export declare const CheckboxWidget: default_2.FC<CheckboxWidgetProps>;
+
+export declare type CheckboxWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<CheckboxWidgetRenderProps, keyof WidgetProps>;
+
+export declare const CheckboxWidgetRender: default_2.NamedExoticComponent<CheckboxWidgetRenderProps>;
+
+declare type CheckboxWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    checkboxProps?: Partial<CheckboxProps>;
+};
+
+/** 紧凑型表单字段样式 (TextField 系列) */
+export declare const compactFieldStyles: SxProps<Theme>;
+
 /**
- * 计算所有字段的状态
+ * 编译后的 Schema (Runtime 输入)
  */
-export declare function computeAllFieldStates<T extends Record<string, unknown>>(parsed: ParsedSchema<T>, values: Record<string, unknown>, globalDisabled?: boolean, globalReadOnly?: boolean): FieldStatesMap;
+export declare type CompiledSchema = {
+    meta: SchemaMeta;
+    fields: Record<string, FieldConfig>;
+    /** 布局树 */
+    layout: LayoutNode[];
+    /** 扁平化的规则列表，已排序 */
+    rules: SchemaRule[];
+    /** 反向依赖索引: DepField -> Rules[] */
+    dependencyMap: Map<string, SchemaRule[]>;
+    /** 拓扑排序序列 (字段名) */
+    topologicalOrder: string[];
+    /** 静态分析报告 */
+    staticAnalysisReport?: {
+        cycles: string[][];
+        isolatedFields: string[];
+    };
+};
 
-/** 计算配置 */
-export declare type ComputeConfig = {
-    /** 表达式字符串，如 "price * quantity" */
-    expr: string;
-    /** 依赖字段（可选，自动从 expr 解析） */
-    dependencies?: string[];
-    /** 小数精度（可选，默认为不处理） */
-    precision?: number;
-    /** 舍入模式（可选，默认为 'round' 四舍五入） */
-    roundMode?: 'round' | 'ceil' | 'floor';
+export declare type CompilerOptions = {
+    /** 当前运行时版本 (用于兼容性检查) */
+    runtimeVersion?: string;
+    /** 是否启用严格模式 (循环依赖时抛出异常) */
+    strictMode?: boolean;
+    /** 是否跳过安全验证 (不推荐) */
+    skipSecurityValidation?: boolean;
 };
 
+/** 创建自定义配置的编译器 */
+export declare function createCompiler(options: CompilerOptions): SchemaCompiler;
+
 /**
- * 计算单个字段的状态
+ * 创建绑定了 form 的 FieldAdapter
+ * 减少重复传递 form 参数
  */
-export declare function computeFieldState(field: FieldSchema, values: Record<string, unknown>, globalDisabled?: boolean, globalReadOnly?: boolean): FieldState;
+export declare function createFieldAdapter(form: AnyFormApi_4): (props: Omit<FieldAdapterProps, "form">) => JSX.Element;
 
-/** 条件表达式：简单或复合或函数 */
-export declare type ConditionExpression = SimpleCondition | CompoundCondition | ((values: Record<string, unknown>) => boolean);
+/**
+ * 快捷函数：为字段创建验证 schema
+ *
+ * @example
+ * ```tsx
+ * const schema = createFieldValidator(
+ *   'email',
+ *   'Text',
+ *   [{ type: 'required' }, { type: 'email' }],
+ *   { label: '邮箱' }
+ * );
+ * ```
+ */
+export declare function createFieldValidator(fieldName: string, component: string, rules: ValidationRule[], options?: Omit<RulesAdapterOptions, "fieldType">): v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
 
 /**
- * 创建动态 resolver（用于 react-hook-form）
+ * 创建验证预设注册表
+ *
+ * @param initialRules 初始规则集 (会与默认规则合并)
+ * @returns 注册表实例
+ *
+ * @example
+ * ```tsx
+ * const registry = createValidationRegistry({
+ *   // 覆盖默认的 email 规则
+ *   email: (config) => v.check(
+ *     (val) => isEmpty(val) || /@(163|qq|gmail)\.com$/.test(String(val)),
+ *     config?.message ?? '只支持 163、QQ、Gmail 邮箱'
+ *   ),
+ *   // 添加新规则
+ *   idNumber: (config) => v.check(
+ *     (val) => isEmpty(val) || /^\d{18}$/.test(String(val)),
+ *     config?.message ?? '请输入18位身份证号'
+ *   ),
+ * });
+ * ```
  */
-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 function createValidationRegistry(initialRules?: Record<string, RuleFactory>): ValidationPresetRegistry;
 
-/** 自定义组件 */
-export declare const CustomWidget: WidgetComponent;
+/**
+ * 自定义组件
+ *
+ * 允许用户完全自定义表单控件的渲染
+ *
+ * @example
+ * ```tsx
+ * // 使用 children 函数
+ * <CustomWidget
+ *   form={form}
+ *   name="custom"
+ *   children={({ value, onChange }) => (
+ *     <MyCustomInput value={value} onChange={onChange} />
+ *   )}
+ * />
+ *
+ * // 使用 component
+ * <CustomWidget
+ *   form={form}
+ *   name="custom"
+ *   component={MyCustomInput}
+ *   componentProps={{ variant: 'outlined' }}
+ * />
+ * ```
+ */
+export declare const CustomWidget: default_2.FC<CustomWidgetProps>;
+
+export declare type CustomWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<CustomWidgetRenderProps, keyof WidgetProps>;
+
+/**
+ * 自定义组件渲染
+ *
+ * 支持三种方式渲染自定义内容：
+ * 1. children 函数：接收完整的 props，返回 ReactNode
+ * 2. children ReactNode：直接渲染
+ * 3. component：自定义组件
+ */
+export declare const CustomWidgetRender: default_2.NamedExoticComponent<CustomWidgetRenderProps>;
+
+export declare type CustomWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    /** 自定义渲染函数 */
+    children?: default_2.ReactNode | ((props: WidgetProps & Record<string, any>) => default_2.ReactNode);
+    /** 自定义组件 */
+    component?: default_2.ComponentType<WidgetProps & Record<string, any>>;
+    /** 传递给自定义组件的额外属性 */
+    componentProps?: Record<string, any>;
+};
 
 /** 日期格式 */
 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 DateTimeWidget: default_2.FC<DateTimeWidgetProps>;
+
+export declare type DateTimeWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<DateTimeWidgetRenderProps, keyof WidgetProps>;
+
+export declare const DateTimeWidgetRender: default_2.NamedExoticComponent<DateTimeWidgetRenderProps>;
 
-/** 日期选择 */
-export declare const DateWidget: WidgetComponent;
+export declare type DateTimeWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    format?: string;
+    minDateTime?: string;
+    maxDateTime?: string;
+    ampm?: boolean;
+};
+
+export declare const DateWidget: default_2.FC<DateWidgetProps>;
+
+export declare type DateWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<DateWidgetRenderProps, keyof WidgetProps>;
+
+export declare const DateWidgetRender: default_2.NamedExoticComponent<DateWidgetRenderProps>;
+
+declare type DateWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    format?: string;
+    min?: string;
+    max?: string;
+};
+
+export declare const defaultRuleFactories: Record<string, RuleFactory>;
 
 /**
  * 默认 Widget 映射表
+ * 用于根据 component 类型自动选择对应的 Widget
+ *
+ * 使用 *Render 版本的组件 (纯渲染函数)，接收 WidgetProps
  */
-export declare const defaultWidgets: Record<string, WidgetComponent>;
+export declare const defaultWidgets: Record<string, WidgetRenderFn>;
 
 /**
- * 求值条件表达式
- * @param condition 条件表达式
- * @param values 当前表单值
- * @returns 条件是否满足
+ * 依赖分析器 (V4 Enhanced)
+ * 负责检测循环依赖、孤立字段并生成拓扑排序
  */
-export declare function evaluateCondition(condition: ConditionExpression, values: Record<string, unknown>): boolean;
+export declare class DependencyAnalyzer {
+    /** 是否启用严格模式 (循环依赖时抛出异常) */
+    private strictMode;
+    constructor(options?: {
+        strictMode?: boolean;
+    });
+    /**
+     * 分析规则集合，返回拓扑排序和反向依赖索引
+     * @param rules 扁平化的规则列表
+     * @param allFieldNames 所有字段名 (用于检测孤立字段)
+     * @returns 分析结果
+     */
+    analyze(rules: SchemaRule[], allFieldNames?: string[]): AnalysisResult;
+    /**
+     * 检测孤立字段
+     * 孤立字段：既不依赖其他字段，也不被其他字段依赖
+     */
+    private findIsolatedFields;
+    /**
+     * Tarjan's algorithm for finding SCCs (Strongly Connected Components)
+     * Only components with size > 1 or self-loops are cycles.
+     */
+    private findCycles;
+    /**
+     * Topological Sort (DFS based)
+     */
+    private topologicalSort;
+}
+
+export declare const dependencyAnalyzer: DependencyAnalyzer;
 
 /**
- * 从条件表达式中提取依赖字段
- * @param condition 条件表达式
- * @returns 依赖字段名数组
+ * 副作用系统 (Runtime Core - V4 Enhanced)
+ * 负责调度所有派生规则、条件判断和联动逻辑
+ *
+ * 核心特性:
+ * - Snapshot Batching: 基于状态快照计算，最后合并提交
+ * - Conflict Resolution: 高优先级覆盖低优先级
+ * - Error Boundary: 规则失败不阻断表单
+ * - Runtime Freezing: scope 对象浅冻结防止修改
  */
-export declare function extractDependencies(condition: ConditionExpression): string[];
+export declare class EffectSystem {
+    private schema;
+    private form;
+    private scheduler;
+    private config;
+    private pendingRules;
+    private isBatching;
+    private traces;
+    /** 字段 Meta 缓存 (避免频繁读取 Form State) */
+    private metaCache;
+    /** 字段订阅者 */
+    private listeners;
+    constructor(schema: CompiledSchema, form: AnyFormApi, scheduler: AsyncScheduler, config?: EffectSystemConfig);
+    /**
+     * 订阅字段 Meta 变更
+     */
+    subscribe(fieldName: string, listener: () => void): () => void;
+    /**
+     * 初始化所有字段的 Meta 缓存
+     */
+    private initializeMetaCache;
+    /**
+     * 获取字段的 Meta 状态
+     */
+    getFieldMeta(fieldName: string): FieldMeta | undefined;
+    /**
+     * 获取所有 Meta 快照
+     */
+    getAllMeta(): Record<string, FieldMeta>;
+    /**
+     * 获取追踪日志
+     */
+    getTraces(): readonly EffectTrace[];
+    /**
+     * 清除追踪日志
+     */
+    clearTraces(): void;
+    /**
+     * 清除所有订阅者
+     */
+    clearListeners(): void;
+    /**
+     * 触发依赖更新
+     * 当 TanStack Form 字段值变化时调用此方法
+     * @param changedField 变化的字段名
+     */
+    notifyFieldChange(changedField: string): void;
+    /**
+     * 调度批量更新 (Microtask)
+     */
+    private scheduleBatchUpdate;
+    /**
+     * 递归冻结对象 (Deep Freeze)
+     * 确保 EvalScope 在运行时绝对不可变
+     */
+    private deepFreeze;
+    /**
+     * 执行批量更新
+     */
+    private flushUpdates;
+    /**
+     * 执行 derive 规则
+     */
+    private executeDeriveRule;
+    /**
+     * 执行 gate 规则
+     */
+    private executeGateRule;
+    /**
+     * 执行 options 规则 (异步)
+     */
+    private executeOptionsRule;
+    /**
+     * 执行 effect 规则
+     */
+    private executeEffectRule;
+    /**
+     * 提交变更到 Form
+     */
+    private commitUpdates;
+    /**
+     * 通知字段订阅者
+     */
+    private notifyListeners;
+    /**
+     * 通过路径获取值 (支持嵌套路径如 "a.b.c")
+     */
+    private getValueByPath;
+    /**
+     * 简单的深拷贝
+     */
+    private cloneDeep;
+    /**
+     * 深度比较两个值是否相等
+     */
+    private isEqual;
+    /**
+     * 记录追踪日志
+     */
+    private logTrace;
+    /**
+     * 初始化执行所有规则 (首次渲染)
+     */
+    initialize(): void;
+    /**
+     * 更新外部上下文
+     */
+    updateContext(context: Record<string, any>): void;
+}
 
-export declare const FieldRenderer: typeof FieldRendererInner;
+/**
+ * EffectSystem 配置
+ */
+export declare type EffectSystemConfig = {
+    /** 是否启用 DevTools 追踪 */
+    enableTracing?: boolean;
+    /** 追踪日志最大条数 */
+    maxTraceCount?: number;
+    /** 错误回调 */
+    onError?: (error: Error, context: {
+        rule: SchemaRule;
+        target: string;
+    }) => void;
+    /** 外部上下文 (注入到 EvalScope.context) */
+    externalContext?: Record<string, any>;
+};
 
 /**
- * 字段渲染器组件
- * 负责根据 Schema 渲染单个表单字段
+ * 效果追踪日志
  */
-declare function FieldRendererInner<T extends FieldValues = FieldValues>({ field, index, values, form, disabled, readOnly, widgets, optionsMap, useGrid, }: FieldRendererProps<T>): JSX.Element | null;
+export declare type EffectTrace = {
+    ruleId: string;
+    target: string;
+    type: SchemaRule["type"];
+    deps?: string[];
+    duration: number;
+    result: any;
+    error?: Error;
+    timestamp: number;
+};
 
-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;
-}
+/**
+ * 运行时评估作用域
+ * 必须在运行时被 Object.freeze() 浅冻结
+ */
+export declare type EvalScope = Readonly<{
+    values: Record<string, any>;
+    meta: Record<string, any>;
+    context: Record<string, any>;
+}>;
 
-/** 字段 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>[];
+/**
+ * 字段适配器 (V4 Enhanced)
+ *
+ * 特性:
+ * - Selector Subscription: 细粒度订阅减少重渲染
+ * - Runtime Meta 集成: 自动读取 visible/disabled/required
+ * - Validation 集成: 支持 Valibot schema 和预设规则数组
+ */
+export declare const FieldAdapter: default_2.NamedExoticComponent<FieldAdapterProps>;
+
+export declare type FieldAdapterProps = {
+    form: AnyFormApi_4;
+    name: string;
+    /**
+     * 校验规则
+     * - Valibot schema: 直接使用 valibot 校验
+     * - PresetRule[]: 预设规则数组，格式为 [{type: 'required', message: '必填'}, {type: 'email'}]
+     */
+    validate?: any | PresetRule[];
+    render: (props: WidgetProps) => default_2.ReactNode;
+    /** 额外的 props 透传 */
+    fieldProps?: Record<string, any>;
+};
+
+/**
+ * 字段配置 (Compiler 输出)
+ */
+export declare type FieldConfig = {
+    name: string;
+    component: string;
+    defaultValue?: any;
+    props?: Record<string, any>;
+    validate?: any;
+};
+
+/**
+ * 字段 Meta 状态
+ */
+export declare type FieldMeta = {
+    isVisible: boolean;
+    isDisabled: boolean;
+    isRequired: boolean;
+    options?: any[];
+    error?: string;
+};
+
+/** 字段类型 */
+export declare type FieldType = "text" | "number" | "boolean" | "select" | "array" | "date" | "unknown";
+
+/**
+ * FormList 动态列表组件
+ *
+ * 用于管理动态数组数据，支持添加、删除、复制行
+ *
+ * @example
+ * ```tsx
+ * // Schema 配置
+ * {
+ *   name: 'users',
+ *   component: 'FormList',
+ *   ui: {
+ *     label: '用户列表',
+ *     minItems: 1,
+ *     maxItems: 5,
+ *     addText: '添加用户',
+ *     copyable: true,
+ *   },
+ *   children: [
+ *     { name: 'name', component: 'Text', ui: { label: '姓名' } },
+ *     { name: 'age', component: 'Number', ui: { label: '年龄' } },
+ *   ],
+ * }
+ * ```
+ */
+export declare const FormListWidget: default_2.NamedExoticComponent<FormListWidgetRenderProps>;
+
+export declare type FormListWidgetProps = {
+    form: any;
+    name: string;
+} & Omit<FormListWidgetRenderProps, keyof WidgetProps>;
+
+/**
+ * FormList 动态列表组件
+ *
+ * 支持动态添加/删除/复制行
+ */
+export declare const FormListWidgetRender: default_2.NamedExoticComponent<FormListWidgetRenderProps>;
+
+export declare type FormListWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    /** 布局子节点 (由 SchemaRenderer 传入) */
+    layoutChildren?: LayoutNode[];
     /** 最小行数 */
     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[];
-    /** 组件透传属性 (快捷方式，等同于 ui.props) */
-    fieldProps?: Record<string, unknown>;
-};
-
-/**
- * 字段状态计算引擎
- *
- * 计算每个字段的运行时状态：
- * - visible: 是否显示
- * - disabled: 是否禁用
- * - required: 是否必填
- * - readonly: 是否只读
- */
-/** 单个字段的运行时状态 */
-export declare type FieldState = {
-    /** 是否可见 */
-    visible: boolean;
-    /** 是否禁用 */
-    disabled: boolean;
-    /** 是否必填 */
-    required: boolean;
-    /** 是否只读 */
-    readonly: boolean;
+    /** 空状态提示 */
+    emptyText?: string;
+    /** 显示行号 */
+    showIndex?: boolean;
+    /** 每行的默认值 */
+    itemDefaultValue?: Record<string, any>;
 };
 
-/** 所有字段的状态映射 */
-export declare type FieldStatesMap = Map<string, FieldState>;
+/**
+ * 表单运行时 (Facade - V4)
+ *
+ * 统一管理 EffectSystem 和 AsyncScheduler，提供简洁的 API。
+ */
+export declare class FormRuntime {
+    readonly effectSystem: EffectSystem;
+    readonly asyncScheduler: AsyncScheduler;
+    readonly schema: CompiledSchema;
+    private form;
+    private initialized;
+    constructor(schema: CompiledSchema, form: AnyFormApi_2, config?: RuntimeConfig);
+    /**
+     * 获取 TanStack Form 实例 (仅用于调试或高级用法)
+     */
+    getForm(): AnyFormApi_2;
+    /**
+     * 初始化运行时 (执行所有规则)
+     */
+    initialize(): void;
+    /**
+     * 通知字段变更
+     */
+    notifyChange(field: string): void;
+    /**
+     * 批量通知字段变更
+     */
+    notifyChanges(fields: string[]): void;
+    /**
+     * 订阅字段 Meta 变更
+     */
+    subscribe(fieldName: string, listener: () => void): () => void;
+    /**
+     * 获取字段 Meta
+     */
+    getFieldMeta(fieldName: string): FieldMeta | undefined;
+    /**
+     * 获取所有字段 Meta
+     */
+    getAllMeta(): Record<string, FieldMeta>;
+    /**
+     * 更新外部上下文
+     */
+    updateContext(context: Record<string, any>): void;
+    /**
+     * 获取调度器
+     */
+    get scheduler(): AsyncScheduler;
+    /**
+     * 获取追踪日志
+     */
+    getTraces(): readonly EffectTrace[];
+    /**
+     * 清除追踪日志
+     */
+    clearTraces(): void;
+    /**
+     * 使缓存失效并重新计算
+     */
+    invalidateAndRefresh(field?: string): void;
+    /**
+     * 销毁运行时
+     */
+    destroy(): void;
+}
 
 /**
- * FormList 动态列表组件
- * 支持动态添加/删除/复制行
+ * 获取所有已注册的 Widget 类型
  */
-export declare const FormListWidget: WidgetComponent;
+export declare function getRegisteredWidgetTypes(): string[];
 
 /**
- * 获取字段的所有下游依赖（递归）
- * 用于判断哪些字段需要重新计算
+ * 获取 Widget 组件
  */
-export declare function getDownstreamFields(fieldName: string, dependencyGraph: Map<string, Set<string>>): Set<string>;
+export declare function getWidget(type: string): WidgetRenderFn | undefined;
+
+/** 全局默认验证预设注册表 */
+export declare const globalValidationRegistry: ValidationPresetRegistry;
 
 /**
- * 获取需要监听的依赖字段
- * 用于构建 useWatch 的 name 数组
+ * 分组组件
+ *
+ * 用于将多个表单字段组织在一起
+ *
+ * @example
+ * ```tsx
+ * // Schema 配置
+ * {
+ *   name: 'personalInfo',
+ *   component: 'Group',
+ *   ui: {
+ *     label: '个人信息',
+ *     variant: 'card',
+ *   },
+ *   children: [
+ *     { name: 'name', component: 'Text', ui: { label: '姓名' } },
+ *     { name: 'age', component: 'Number', ui: { label: '年龄' } },
+ *   ],
+ * }
+ * ```
  */
-export declare function getWatchFields<T extends Record<string, unknown>>(parsed: ParsedSchema<T>): string[];
+export declare const GroupWidget: default_2.FC<GroupWidgetProps>;
+
+export declare type GroupWidgetProps = {} & GroupWidgetRenderProps;
 
 /**
- * Grid 布局组件
- * 使用 MUI Grid 实现响应式网格布局
+ * 分组组件渲染
+ *
+ * 将多个字段组合在一起，支持不同的显示样式
  */
-export declare const GridLayout: ({ spacing, children }: GridLayoutProps) => JSX.Element;
+export declare const GroupWidgetRender: default_2.NamedExoticComponent<GroupWidgetRenderProps>;
 
-export declare interface GridLayoutProps {
-    /** 间距 */
+export declare type GroupWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    /** 布局子节点 (由 SchemaRenderer 传入) */
+    layoutChildren?: LayoutNode[];
+    /** 显示样式: card 卡片 | divider 分割线 | none 无边框 */
+    variant?: "card" | "divider" | "none";
+    /** 是否折叠 (TODO: 未实现) */
+    collapsible?: boolean;
+    /** Grid 间距 */
     spacing?: number;
-    /** 子元素 */
-    children: ReactNode;
+};
+
+export declare const HiddenWidget: default_2.FC<HiddenWidgetProps>;
+
+export declare type HiddenWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+};
+
+/**
+ * 隐藏字段渲染组件
+ *
+ * 渲染一个隐藏的 input 元素，用于存储不可见的表单数据
+ */
+export declare const HiddenWidgetRender: default_2.NamedExoticComponent<WidgetProps>;
+
+export declare type HiddenWidgetRenderProps = WidgetProps;
+
+/**
+ * 从字段配置推断字段类型
+ */
+export declare function inferFieldType(component: string): FieldType;
+
+/**
+ * 检测是否为预设规则数组
+ * @param value 待检测的值
+ * @returns 是否为预设规则数组
+ */
+export declare function isPresetRulesArray(value: unknown): value is PresetRule[];
+
+export declare const LayoutContext: default_2.Context<LayoutContextType | null>;
+
+export declare interface LayoutContextType {
+    renderField: (fieldPath: string, layoutChildren?: LayoutNode[]) => default_2.ReactNode;
 }
 
 /**
- * Group 分组组件
- * 将多个字段组合在一行内显示
+ * 布局节点
  */
-export declare const GroupWidget: WidgetComponent;
+export declare type LayoutNode = {
+    type: 'field' | 'container';
+    /** 如果是 field，对应 fieldPath */
+    field?: string;
+    /** 如果是 container，对应组件名 (Grid, Stack, Card...) */
+    component?: string;
+    props?: Record<string, any>;
+    children?: LayoutNode[];
+};
 
-/** 隐藏字段 */
-export declare const HiddenWidget: WidgetComponent;
+export declare const LayoutRenderer: default_2.FC<LayoutRendererProps>;
 
-export declare type LayoutConfig = {
-    /** 布局类型 */
-    type: 'grid' | 'stack';
-    /** 列数（仅 grid） */
-    columns?: number;
-    /** 区域定义（CSS Grid Area 风格） */
-    areas?: string[][];
-    /** 间距 */
-    spacing?: number;
+export declare interface LayoutRendererProps {
+    layout: LayoutNode[];
+    renderField: (fieldPath: string, layoutChildren?: LayoutNode[]) => default_2.ReactNode;
+}
+
+export declare type LinterOptions = {
+    /** 是否检查未使用的字段 */
+    checkUnusedFields?: boolean;
+    /** 是否检查表达式语法 */
+    checkExpressions?: boolean;
+    /** 是否检查组件类型 */
+    checkComponentTypes?: boolean;
+    /** 已知的组件类型列表 */
+    knownComponents?: string[];
+};
+
+export declare type LintMessage = {
+    severity: LintSeverity;
+    field?: string;
+    rule?: string;
+    message: string;
+    suggestion?: string;
+};
+
+export declare type LintResult = {
+    valid: boolean;
+    messages: LintMessage[];
+    errors: LintMessage[];
+    warnings: LintMessage[];
 };
 
 /**
- * 合并默认值与外部传入值
+ * 快捷校验函数
  */
-export declare function mergeDefaultValues<T extends Record<string, unknown>>(parsed: ParsedSchema<T>, externalValues?: Partial<T>): Partial<T>;
+export declare function lintSchema(schema: SchemaInput, options?: LinterOptions): LintResult;
+
+export declare type LintSeverity = "error" | "warning" | "info";
+
+export declare const NumberWidget: default_2.FC<NumberWidgetProps>;
+
+export declare type NumberWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<NumberWidgetRenderProps, keyof WidgetProps>;
 
-/** 数字输入 */
-export declare const NumberWidget: WidgetComponent;
+export declare const NumberWidgetRender: default_2.NamedExoticComponent<NumberWidgetRenderProps>;
+
+declare type NumberWidgetRenderProps = WidgetProps & {
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    inputProps?: Record<string, any>;
+    slotProps?: TextFieldProps["slotProps"];
+};
+
+/** 添加选项成功回调 */
+declare type OnAddOptionSuccess = (newOption: OptionItem, context: {
+    /** 是否为远程模式 */
+    isRemote: boolean;
+    /** 刷新远程数据 (仅远程模式) */
+    refreshRemote?: () => void;
+    /** 追加本地选项 (仅本地模式) */
+    appendLocalOption?: (option: OptionItem) => void;
+}) => void;
 
 export declare type OptionItem = {
     label: string;
     value: string | number | boolean | null;
     disabled?: boolean;
-    /** 唯一标识 (解决 label 重复问题) */
     key?: string | number;
     /** 列表展示文本 (允许与选中后回显的 label 不一致) */
-    listLabel?: React.ReactNode;
+    listLabel?: default_2.ReactNode;
     [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>[];
+/**
+ * 快捷函数：覆盖全局注册表中的预设规则
+ */
+export declare function overridePresetRule(name: string, factory: RuleFactory): void;
+
+/**
+ * 解析 colSpan 为 Grid size props
+ */
+export declare function parseColSpan(colSpan?: number | Record<string, number>): Record<string, number>;
+
+/**
+ * 预设规则配置
+ * @example
+ * ```tsx
+ * // 简写
+ * { type: 'required' }
+ * { type: 'email', message: '请输入有效邮箱' }
+ *
+ * // 带参数
+ * { type: 'minLength', value: 3, message: '至少3个字符' }
+ * { type: 'pattern', value: /^\d+$/, message: '只能输入数字' }
+ * ```
+ */
+export declare type PresetRule = {
+    type: PresetRuleName;
+    value?: any;
+    message?: string;
 };
 
+/** 预设规则名称 */
+export declare type PresetRuleName = "required" | "email" | "phone" | "url" | "minLength" | "maxLength" | "min" | "max" | "pattern" | "idCard" | "integer" | "positive" | "negative" | "alphanumeric" | "chinese" | string;
+
 /**
- * 解析 Schema，生成预处理后的结构
+ * 将预设规则数组转换为 valibot schema
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * const schema = presetToSchema([
+ *   { type: 'required', message: '必填项' },
+ *   { type: 'email', message: '请输入有效邮箱' },
+ * ]);
+ *
+ * // 带参数的规则
+ * const schema = presetToSchema([
+ *   { type: 'required' },
+ *   { type: 'minLength', value: 3, message: '至少3个字符' },
+ *   { type: 'maxLength', value: 20 },
+ * ], { label: '用户名' });
+ * ```
  */
-export declare function parseSchema<T extends Record<string, unknown>>(input: SchemaInput<T>): ParsedSchema<T> & {
-    allFields: FieldSchema<T>[];
+export declare function presetToSchema(rules: PresetRule[], options?: {
+    label?: string;
+    baseType?: "string" | "number" | "any";
+}): v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
+
+export declare const RadioWidget: default_2.FC<RadioWidgetProps>;
+
+export declare type RadioWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<RadioWidgetRenderProps, keyof WidgetProps>;
+
+export declare const RadioWidgetRender: default_2.NamedExoticComponent<RadioWidgetRenderProps>;
+
+declare type RadioWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    /** 选项横向排列，默认 false（纵向） */
+    row?: boolean;
+    /** label 和组件在同一行，默认 false（label 在上） */
+    inline?: boolean;
+    radioProps?: Partial<RadioProps>;
 };
 
-/** 密码输入 */
-export declare const PasswordWidget: WidgetComponent;
+export declare const RatingWidget: default_2.FC<RatingWidgetProps>;
 
-/** 单选组 */
-export declare const RadioWidget: WidgetComponent;
+export declare type RatingWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<RatingWidgetRenderProps, keyof WidgetProps>;
 
-/** 评分 */
-export declare const RatingWidget: WidgetComponent;
+export declare const RatingWidgetRender: default_2.NamedExoticComponent<RatingWidgetRenderProps>;
 
-/** 远程加载配置 (分页/搜索) */
-declare type RemoteConfig = {
+export declare type RatingWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    max?: number;
+    precision?: number;
+    size?: "small" | "medium" | "large";
+    readOnly?: boolean;
+    /** 内联模式：label 和 rating 在同一行 */
+    inline?: boolean;
+};
+
+/**
+ * 快捷函数：注册新的预设规则到全局注册表
+ */
+export declare function registerPresetRule(name: string, factory: RuleFactory): void;
+
+/**
+ * 注册自定义 Widget
+ */
+export declare function registerWidget(type: string, widget: WidgetRenderFn): void;
+
+/**
+ * 批量注册 Widget
+ */
+export declare function registerWidgets(widgets: Record<string, WidgetRenderFn>): void;
+
+export declare type RemoteConfig = {
     /** 获取数据的函数 */
     fetchOptions: (keyword: string, page: number, pageSize: number) => Promise<{
         data: OptionItem[];
         total: number;
         hasMore: boolean;
     }>;
-    /** 每页条数 */
+    /** 每页条数，默认 20 */
     pageSize?: number;
-    /** 搜索防抖时间 (ms) */
+    /** 搜索防抖时间 (ms)，默认 500 */
     debounceTimeout?: number;
-    /** 最小搜索字符数 */
+    /** 最小搜索字符数，默认 0 */
     minSearchLength?: number;
     /** 加载状态回调 */
     onLoadingChange?: (loading: boolean) => void;
@@ -379,167 +1089,814 @@ declare type RemoteConfig = {
     fetchById?: (value: string | number) => Promise<OptionItem | null>;
 };
 
-/** 导出 SchemaForm 组件 */
-export declare const SchemaForm: <T extends FieldValues>(props: SchemaFormProps<T> & {
-    ref?: default_2.Ref<SchemaFormInstance<T>>;
+/**
+ * 渲染带必填标识的标签
+ *
+ * @param label - 标签文本
+ * @param required - 是否必填
+ * @returns 带星号标识的标签
+ */
+export declare const renderLabel: (label: ReactNode, required?: boolean) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | ReactPortal | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | JSX.Element | null | undefined;
+
+/** 规则配置参数 */
+export declare type RuleConfig = {
+    /** 规则参数值 (如 minLength 的长度) */
+    value?: any;
+    /** 自定义错误消息 */
+    message?: string;
+    /** 字段标签 (用于默认消息) */
+    label?: string;
+};
+
+/** 规则工厂函数 - 接收配置，返回 valibot check */
+export declare type RuleFactory = (config?: RuleConfig) => v.PipeItem<any, any, v.BaseIssue<unknown>>;
+
+/** 规则适配器选项 */
+export declare type RulesAdapterOptions = {
+    /** 字段标签（用于默认错误消息） */
+    label?: string;
+    /** 字段类型 */
+    fieldType?: FieldType;
+    /** 当前表单值（用于 custom 规则） */
+    values?: Record<string, unknown>;
+};
+
+/**
+ * 将声明式验证规则转换为 Valibot schema
+ *
+ * @example
+ * ```tsx
+ * const schema = rulesToValibot([
+ *   { type: 'required', message: '必填' },
+ *   { type: 'minLength', value: 3, message: '至少3个字符' },
+ *   { type: 'email' },
+ * ], { label: '邮箱', fieldType: 'text' });
+ * ```
+ */
+export declare function rulesToValibot(rules: ValidationRule[], options?: RulesAdapterOptions): v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
+
+/**
+ * 运行时配置
+ */
+export declare type RuntimeConfig = {
+    /** EffectSystem 配置 */
+    effect?: EffectSystemConfig;
+    /** AsyncScheduler 配置 */
+    async?: AsyncSchedulerConfig;
+    /** 是否自动初始化 (执行所有规则) */
+    autoInitialize?: boolean;
+};
+
+/**
+ * 安全的表达式求值器
+ * 基于 AST 解释执行，禁止 eval/new Function
+ */
+export declare class SafeEvaluator {
+    private allowedGlobals;
+    constructor();
+    /**
+     * 编译表达式为可执行函数
+     * @param expr 表达式字符串
+     * @returns 执行函数
+     * @throws Error 如果表达式无效或包含危险代码
+     */
+    compile(expr: string): (scope: EvalScope) => any;
+    /**
+     * 尝试编译表达式，不抛出异常
+     * @param expr 表达式字符串
+     * @returns 编译结果或 null
+     */
+    tryCompile(expr: string): ((scope: EvalScope) => any) | null;
+    /**
+     * 递归评估 AST 节点
+     */
+    private evaluate;
+    /**
+     * 从表达式中提取变量依赖
+     * @param expr 表达式字符串
+     * @returns 依赖的变量名数组 (去重)
+     */
+    extractDependencies(expr: string): string[];
+    /**
+     * 验证表达式是否安全
+     * @param expr 表达式字符串
+     * @returns 验证结果
+     */
+    validate(expr: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * 递归验证 AST 节点的安全性
+     */
+    private validateNode;
+    private visitIdentifiers;
+}
+
+export declare const safeEvaluator: SafeEvaluator;
+
+/**
+ * Schema 编译器 (V4)
+ */
+export declare class SchemaCompiler {
+    private options;
+    private dependencyAnalyzer;
+    constructor(options?: CompilerOptions);
+    compile(input: SchemaInput): CompiledSchema;
+    /**
+     * 版本兼容性检查
+     */
+    private checkVersion;
+    private processFields;
+    private extractOptionsRule;
+    private extractRule;
+}
+
+/** 默认编译器实例 */
+export declare const schemaCompiler: SchemaCompiler;
+
+export declare type SchemaField = {
+    name: string;
+    component: string;
+    defaultValue?: any;
+    visibleWhen?: string | ((scope: EvalScope) => boolean);
+    disabledWhen?: string | ((scope: EvalScope) => boolean);
+    requiredWhen?: string | ((scope: EvalScope) => boolean);
+    compute?: string | ((scope: EvalScope) => any);
+    /** 校验规则 (Valibot Schema or Adapter) */
+    validate?: any;
+    /**
+     * 选项配置
+     * - 数组：静态选项
+     * - 函数：异步选项（无依赖追踪）
+     * - 对象：异步选项 + 手动指定依赖（推荐用于级联选择）
+     * @example
+     * // 静态选项
+     * options: [{ label: '选项1', value: '1' }]
+     *
+     * // 异步选项（无依赖，仅初始化时加载）
+     * options: async (scope, signal) => fetchOptions()
+     *
+     * // 异步选项 + 依赖（推荐：依赖变化时重新加载）
+     * options: {
+     *   fetcher: async (scope, signal) => fetchCities(scope.values.province),
+     *   deps: ['province']
+     * }
+     */
+    options?: any[] | ((scope: EvalScope, signal?: AbortSignal) => Promise<any[]>) | AsyncOptionsConfig;
+    children?: SchemaField[];
+    /** 栅格布局配置 (MUI Grid size) */
+    colSpan?: number | Record<string, number>;
+    /** 独占一行（组件占满整行，内部宽度由 colSpan 控制） */
+    independent?: boolean;
+    ui?: Record<string, any>;
+};
+
+export declare const SchemaForm: <T extends Record<string, any> = Record<string, any>>(props: SchemaFormProps<T> & {
+    ref?: default_2.ForwardedRef<SchemaFormInstance<T>>;
 }) => default_2.ReactElement;
 
-export declare type SchemaFormInstance<T extends FieldValues = FieldValues> = UseFormReturn<T> & {
+/**
+ * SchemaForm 实例方法 (通过 ref 暴露)
+ */
+export declare interface SchemaFormInstance<T = any> {
     /** 提交表单 */
-    submit: () => Promise<void> | boolean;
-    /** 获取表单值（排除 noSubmit 字段） */
-    getFormValues: () => Partial<T>;
+    submit: () => void;
+    /** 重置表单 */
+    reset: () => void;
+    /** 获取所有值 */
+    getValues: () => T;
+    /** 设置字段值 */
+    setValue: (name: keyof T, value: any) => void;
     /** 批量设置值 */
     setValues: (values: Partial<T>) => void;
-};
+    /** 获取 TanStack Form 实例 */
+    getForm: () => any;
+    /** 获取 Runtime 实例 */
+    getRuntime: () => FormRuntime;
+    /** 获取编译后的 Schema */
+    getCompiledSchema: () => CompiledSchema;
+    /** 触发字段校验 */
+    validate: (name?: string) => Promise<boolean>;
+    /** 清除错误 */
+    clearErrors: (name?: string) => void;
+}
 
-declare type SchemaFormProps<T extends FieldValues = FieldValues> = {
+/**
+ * SchemaForm Props
+ */
+export declare type SchemaFormProps<T extends Record<string, any> = Record<string, any>> = {
     /** Schema 定义 */
-    schema: SchemaInput<T>;
+    schema: SchemaInput;
     /** 默认值 */
     defaultValues?: Partial<T>;
     /** 提交回调 */
-    onSubmit?: (values: T) => void | Promise<void | boolean>;
+    onSubmit?: (values: T) => void | Promise<void>;
     /** 值变化回调 */
     onValuesChange?: (values: T) => void;
-    /** 是否使用 Grid 布局 */
-    grid?: boolean;
+    /** 提交失败回调 */
+    onSubmitFailed?: (errors: any) => void;
+    /** 自定义 Widget 映射 */
+    widgets?: WidgetRegistry;
+    /** 全局禁用 */
+    disabled?: boolean;
     /** 全局只读 */
     readOnly?: boolean;
+    /** 栅格间距 */
+    spacing?: number;
+    /** form 标签的额外属性 */
+    formProps?: Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit">;
+    /** 子元素 (如提交按钮) */
+    children?: ReactNode;
+    /** 容器样式 */
+    sx?: any;
+    /** 编译器配置 */
+    compilerOptions?: UseSchemaFormOptions<T>["compilerOptions"];
+    /** 运行时配置 */
+    runtimeConfig?: UseSchemaFormOptions<T>["runtimeConfig"];
+};
+
+export declare const SchemaFormProvider: default_2.FC<{
+    runtime: FormRuntime;
+    children: default_2.ReactNode;
+}>;
+
+/**
+ * 用户输入的 Schema (Source)
+ */
+export declare type SchemaInput = {
+    meta?: SchemaMeta;
+    fields: SchemaField[];
+};
+
+/**
+ * Schema 校验器
+ *
+ * 在编译时检测 Schema 中的问题
+ */
+export declare class SchemaLinter {
+    private options;
+    constructor(options?: LinterOptions);
+    /**
+     * 校验 Schema
+     */
+    lint(schema: SchemaInput): LintResult;
+    /**
+     * 递归校验字段
+     */
+    private lintFields;
+    /**
+     * 校验表达式
+     */
+    private lintExpression;
+}
+
+/**
+ * 默认 Linter 实例
+ */
+export declare const schemaLinter: SchemaLinter;
+
+/**
+ * Schema 版本与兼容性信息
+ */
+export declare type SchemaMeta = {
+    version: string;
+    compatibleWith?: string[];
+};
+
+/**
+ * Schema 渲染器
+ *
+ * 根据编译后的 Schema 自动渲染表单字段
+ *
+ * @example
+ * ```tsx
+ * <SchemaRenderer
+ *   schema={compiledSchema}
+ *   form={form}
+ *   widgets={{ CustomWidget: MyCustomWidget }}
+ * />
+ * ```
+ */
+export declare const SchemaRenderer: default_2.NamedExoticComponent<SchemaRendererProps>;
+
+export declare type SchemaRendererProps = {
+    /** 编译后的 Schema */
+    schema: CompiledSchema;
+    /** TanStack Form 实例 */
+    form: any;
+    /** 自定义 Widget 映射 (覆盖默认) */
+    widgets?: WidgetRegistry;
     /** 全局禁用 */
     disabled?: boolean;
-    /** 自定义控件 */
-    widgets?: Record<string, WidgetComponent<T>>;
-    /** 子元素 */
-    children?: React.ReactNode;
-    /** 间距 */
+    /** 全局只读 */
+    readOnly?: boolean;
+    /** 栅格间距 */
     spacing?: number;
 };
 
-export declare type SchemaInput<T extends FieldValues = FieldValues> = {
-    /** 字段定义 */
-    fields: FieldSchema<T>[];
-    /** 布局配置（可选，默认使用 colSpan 响应式布局） */
-    layout?: LayoutConfig;
+/**
+ * 规则类型定义
+ */
+export declare type SchemaRule = {
+    type: 'derive';
+    target: string;
+    deps: string[];
+    /** 预编译后的执行函数 */
+    evaluator: (scope: EvalScope) => any;
+    priority: number;
+} | {
+    type: 'gate';
+    target: string;
+    deps: string[];
+    evaluator: (scope: EvalScope) => boolean;
+    effect: 'visible' | 'disabled' | 'required';
+    priority: number;
+} | {
+    type: 'options';
+    target: string;
+    deps: string[];
+    fetcher: (scope: EvalScope, signal: AbortSignal) => Promise<any>;
+    /** 生成缓存 Key 的策略，e.g., `${field}:${hash(deps)}` */
+    cacheKey?: (scope: EvalScope) => string;
+    priority: number;
+} | {
+    type: 'effect';
+    deps: string[];
+    handler: (scope: EvalScope, api: any) => void;
+    priority: number;
 };
 
-/** 简单条件：单字段比较 */
-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;
+/** 搜索清空相关配置 */
+declare type SearchClearConfig = {
+    /** 关闭面板后保持搜索值，默认 false */
+    keepSearchOnClose?: boolean;
+    /** 选中选项后保持搜索值，默认 false */
+    keepSearchOnSelect?: boolean;
+    /** 缓存最后一次非空搜索值，默认 false */
+    cacheSearchKeyword?: boolean;
+    /** 仅清空搜索值，不重置列表，默认 false */
+    clearValueOnly?: boolean;
 };
 
-/** 滑块 */
-export declare const SliderWidget: WidgetComponent;
+export declare const SelectWidget: FC<AutocompleteWidgetProps>;
+
+export declare type SelectWidgetProps = AutocompleteWidgetProps;
 
 /**
- * Stack 布局组件
- * 使用 MUI Stack 实现垂直堆叠布局
+ * SelectWidget is now an alias for AutocompleteWidget.
+ * It provides unified functionality using MUI Autocomplete.
  */
-export declare const StackLayout: ({ spacing, children }: StackLayoutProps) => JSX.Element;
+export declare const SelectWidgetRender: NamedExoticComponent<AutocompleteWidgetRenderProps>;
 
-export declare interface StackLayoutProps {
-    /** 间距 */
-    spacing?: number;
-    /** 子元素 */
-    children: ReactNode;
-}
+export declare const SliderWidget: default_2.FC<SliderWidgetProps>;
+
+export declare type SliderWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<SliderWidgetRenderProps, keyof WidgetProps>;
+
+export declare const SliderWidgetRender: default_2.NamedExoticComponent<SliderWidgetRenderProps>;
+
+export declare type SliderWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    marks?: boolean | {
+        value: number;
+        label?: string;
+    }[];
+    valueLabelDisplay?: "on" | "auto" | "off";
+    showValue?: boolean;
+    /** 内联模式：label 和 slider 在同一行 */
+    inline?: boolean;
+};
+
+/**
+ * 静态分析报告
+ */
+export declare type StaticAnalysisReport = {
+    /** 循环依赖 (SCC with size > 1) */
+    cycles: string[][];
+    /** 孤立字段 (无入边也无出边的节点，即没有依赖也不被依赖) */
+    isolatedFields: string[];
+    /** 警告信息 */
+    warnings: string[];
+};
+
+/** Suffix 按钮渲染函数 */
+declare type SuffixButtonRender = (searchValue: string, hasOptions: boolean) => ButtonConfig | false | null;
+
+export declare const SwitchWidget: default_2.FC<SwitchWidgetProps>;
+
+export declare type SwitchWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<SwitchWidgetRenderProps, keyof WidgetProps>;
+
+export declare const SwitchWidgetRender: default_2.NamedExoticComponent<SwitchWidgetRenderProps>;
+
+declare type SwitchWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    switchProps?: Partial<SwitchProps>;
+};
+
+/**
+ * 文本输入组件 (MUI TextField)
+ *
+ * 包含 FieldAdapter，可独立使用
+ *
+ * @example
+ * ```tsx
+ * <TextWidget form={form} name="username" label="用户名" />
+ * ```
+ */
+export declare const TextWidget: default_2.FC<TextWidgetProps>;
+
+/**
+ * 独立组件 Props (带 form/name)
+ */
+export declare type TextWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<TextWidgetRenderProps, keyof WidgetProps>;
+
+/**
+ * 文本输入渲染组件
+ *
+ * 接收 WidgetProps，不包含 FieldAdapter
+ */
+export declare const TextWidgetRender: default_2.NamedExoticComponent<TextWidgetRenderProps>;
+
+/**
+ * 纯渲染组件 Props (用于 SchemaRenderer)
+ */
+export declare type TextWidgetRenderProps = WidgetProps & {
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    multiline?: boolean;
+    rows?: number;
+    type?: "text" | "password" | "email" | "url" | "tel";
+    inputProps?: Record<string, any>;
+    slotProps?: TextFieldProps["slotProps"];
+};
+
+export declare const TIME_FORMAT = "HH:mm";
+
+export declare const TimeWidget: default_2.FC<TimeWidgetProps>;
+
+export declare type TimeWidgetProps = {
+    form: any;
+    name: string;
+    validate?: any;
+} & Omit<TimeWidgetRenderProps, keyof WidgetProps>;
+
+export declare const TimeWidgetRender: default_2.NamedExoticComponent<TimeWidgetRenderProps>;
+
+export declare type TimeWidgetRenderProps = WidgetProps & {
+    label?: string;
+    helperText?: string;
+    format?: string;
+    ampm?: boolean;
+    /** 分钟步长，默认 1 */
+    minutesStep?: number;
+    /** 秒步长，默认无 */
+    secondsStep?: number;
+};
+
+export declare const useLayoutContext: () => LayoutContextType;
+
+export declare const useRuntime: () => FormRuntime;
+
+/**
+ * Schema Form 主 Hook (V4)
+ *
+ * 整合 Schema 编译、TanStack Form 和 Runtime
+ *
+ * @example
+ * ```tsx
+ * const { form, runtime } = useSchemaForm({
+ *   schema: mySchema,
+ *   defaultValues: { name: '' },
+ *   onSubmit: (values) => console.log(values),
+ * });
+ * ```
+ */
+export declare function useSchemaForm<T extends Record<string, any> = Record<string, any>>(options: UseSchemaFormOptions<T>): UseSchemaFormReturn<T>;
+
+export declare type UseSchemaFormOptions<T extends Record<string, any> = Record<string, any>> = {
+    /** Schema 输入 */
+    schema: SchemaInput;
+    /** 默认值 */
+    defaultValues?: Partial<T>;
+    /** 提交回调 */
+    onSubmit?: (values: T) => void | Promise<void>;
+    /** 值变化回调 */
+    onValuesChange?: (values: T) => void;
+    /** 编译器配置 */
+    compilerOptions?: CompilerOptions;
+    /** 运行时配置 */
+    runtimeConfig?: RuntimeConfig;
+    /** TanStack Form 额外配置 */
+    formOptions?: Record<string, any>;
+};
 
-/** 开关 */
-export declare const SwitchWidget: WidgetComponent;
+export declare type UseSchemaFormReturn<T extends Record<string, any> = Record<string, any>> = {
+    /** TanStack Form 实例 */
+    form: AnyFormApi_3;
+    /** 运行时实例 */
+    runtime: FormRuntime;
+    /** 编译后的 Schema */
+    compiledSchema: CompiledSchema;
+    /** 提交表单 */
+    handleSubmit: () => void;
+    /** 重置表单 */
+    handleReset: () => void;
+    /** 获取表单值 */
+    getValues: () => T;
+    /** 设置字段值 */
+    setValue: (name: keyof T, value: any) => void;
+};
 
-/** 多行文本 */
-export declare const TextareaWidget: WidgetComponent;
+/**
+ * 验证预设 Hook
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const { toSchema, override, register } = useValidationPresets({
+ *     extend: {
+ *       // 覆盖默认 email 规则 - 只允许特定后缀
+ *       email: (config) => v.check(
+ *         (val) => !val || /@(163|qq|gmail)\.com$/.test(String(val)),
+ *         config?.message ?? '只支持 163、QQ、Gmail 邮箱'
+ *       ),
+ *     },
+ *   });
+ *
+ *   // 动态添加新规则
+ *   useEffect(() => {
+ *     register('companyEmail', (config) => v.check(
+ *       (val) => !val || /@mycompany\.com$/.test(String(val)),
+ *       config?.message ?? '请使用公司邮箱'
+ *     ));
+ *   }, []);
+ *
+ *   // 使用预设规则
+ *   const emailSchema = toSchema([
+ *     { type: 'required', message: '邮箱必填' },
+ *     { type: 'email' },
+ *   ]);
+ *
+ *   return <SchemaForm ... />;
+ * }
+ * ```
+ */
+export declare function useValidationPresets(options?: UseValidationPresetsOptions): UseValidationPresetsReturn;
 
-/** 文本输入 */
-export declare const TextWidget: WidgetComponent;
+/**
+ * 使用 Provider 中的验证预设
+ *
+ * 如果没有 Provider，则使用默认全局预设
+ */
+export declare function useValidationPresetsContext(): UseValidationPresetsReturn;
 
-/** 时间选择 */
-export declare const TimeWidget: WidgetComponent;
+export declare type UseValidationPresetsOptions = {
+    /**
+     * 是否使用独立的注册表实例
+     * - true: 创建新的注册表，不影响全局
+     * - false: 使用全局注册表 (默认)
+     */
+    isolated?: boolean;
+    /**
+     * 初始规则扩展
+     * 可用于覆盖默认规则或添加新规则
+     */
+    extend?: Record<string, RuleFactory>;
+};
+
+export declare type UseValidationPresetsReturn = {
+    /**
+     * 注册新的预设规则
+     * @param name 规则名称
+     * @param factory 规则工厂函数
+     */
+    register: (name: string, factory: RuleFactory) => void;
+    /**
+     * 覆盖已有的预设规则
+     * @param name 规则名称
+     * @param factory 规则工厂函数
+     */
+    override: (name: string, factory: RuleFactory) => void;
+    /**
+     * 批量注册/覆盖规则
+     * @param rules 规则映射
+     */
+    extend: (rules: Record<string, RuleFactory>) => void;
+    /**
+     * 检查规则是否存在
+     */
+    has: (name: string) => boolean;
+    /**
+     * 获取所有已注册的规则名称
+     */
+    getNames: () => string[];
+    /**
+     * 将预设规则数组转换为 valibot schema
+     *
+     * @example
+     * ```tsx
+     * const schema = toSchema([
+     *   { type: 'required', message: '必填' },
+     *   { type: 'email', message: '请输入有效邮箱' },
+     * ]);
+     *
+     * // 带参数
+     * const schema = toSchema([
+     *   { type: 'required' },
+     *   { type: 'minLength', value: 3, message: '至少3个字符' },
+     * ], { label: '用户名' });
+     * ```
+     */
+    toSchema: (rules: PresetRule[], options?: {
+        label?: string;
+        baseType?: "string" | "number" | "any";
+    }) => v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
+    /**
+     * 获取原始注册表实例
+     */
+    registry: ValidationPresetRegistry;
+};
+
+/**
+ * 表单级校验适配器
+ */
+export declare const valibotFormValidator: (schemaOrRules: any) => ({ value }: {
+    value: any;
+}) => string | undefined;
+
+/**
+ * 将 Valibot Schema 或预设规则数组转换为 TanStack Form Validator
+ * 支持同步和异步校验
+ *
+ * @example 支持两种校验格式
+ * ```tsx
+ * // 格式 1: Valibot Schema (高度自定义)
+ * validate: v.pipe(v.string(), v.email('请输入有效邮箱'))
+ *
+ * // 格式 2: 预设规则数组 (简洁声明式)
+ * validate: [
+ *   { type: 'required', message: '必填项' },
+ *   { type: 'email', message: '请输入有效邮箱' },
+ * ]
+ * ```
+ */
+export declare const valibotValidator: (schemaOrRules: any) => ({ value }: {
+    value: any;
+}) => any;
+
+/** 验证预设注册表类型 */
+export declare type ValidationPresetRegistry = {
+    /** 获取规则工厂 */
+    get: (name: string) => RuleFactory | undefined;
+    /** 注册新规则 */
+    register: (name: string, factory: RuleFactory) => void;
+    /** 覆盖已有规则 */
+    override: (name: string, factory: RuleFactory) => void;
+    /** 批量注册规则 */
+    registerAll: (rules: Record<string, RuleFactory>) => void;
+    /** 检查规则是否存在 */
+    has: (name: string) => boolean;
+    /** 获取所有规则名称 */
+    getNames: () => string[];
+    /** 将预设规则数组转换为 valibot schema */
+    toSchema: (rules: PresetRule[], options?: {
+        label?: string;
+        baseType?: "string" | "number" | "any";
+    }) => v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>;
+};
+
+/**
+ * 验证预设 Provider
+ *
+ * 用于在应用级别配置验证预设，所有子组件共享
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ValidationPresetsProvider
+ *       extend={{
+ *         email: (config) => v.check(
+ *           (val) => !val || /@company\.com$/.test(String(val)),
+ *           '请使用公司邮箱'
+ *         ),
+ *         employeeId: (config) => v.check(
+ *           (val) => !val || /^EMP\d{6}$/.test(String(val)),
+ *           '员工编号格式不正确'
+ *         ),
+ *       }}
+ *     >
+ *       <MyForms />
+ *     </ValidationPresetsProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function ValidationPresetsProvider({ children, extend, isolated, }: ValidationPresetsProviderProps): JSX.Element;
+
+export declare type ValidationPresetsProviderProps = {
+    children: ReactNode;
+    /**
+     * 扩展规则
+     */
+    extend?: Record<string, RuleFactory>;
+    /**
+     * 是否使用独立注册表
+     */
+    isolated?: boolean;
+};
 
 /** 基础验证规则 */
 export declare type ValidationRule = {
-    type: 'required';
+    type: "required";
     message?: string;
 } | {
-    type: 'minLength';
+    type: "minLength";
     value: number;
     message?: string;
 } | {
-    type: 'maxLength';
+    type: "maxLength";
     value: number;
     message?: string;
 } | {
-    type: 'min';
+    type: "min";
     value: number;
     message?: string;
 } | {
-    type: 'max';
+    type: "max";
     value: number;
     message?: string;
 } | {
-    type: 'pattern';
+    type: "pattern";
     value: string | RegExp;
     message?: string;
 } | {
-    type: 'email';
+    type: "email";
     message?: string;
 } | {
-    type: 'url';
+    type: "url";
     message?: string;
 } | {
-    type: 'custom';
+    type: "custom";
     validate: (value: unknown, values: unknown) => boolean | string;
 } | {
-    type: 'array';
+    type: "array";
     minItems?: number;
     maxItems?: number;
     message?: string;
 };
 
-/** Widget 组件类型 */
-export declare type WidgetComponent<T extends FieldValues = FieldValues> = React.ComponentType<WidgetProps<T>>;
+export declare interface WidgetProps {
+    /** 字段值 */
+    value: any;
+    /** 值变更回调 */
+    onChange: (val: any) => void;
+    /** 失焦回调 */
+    onBlur: () => void;
+    /** 错误信息 */
+    error?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 是否可见 */
+    visible?: boolean;
+    /** 是否必填 */
+    required?: boolean;
+    /** 选项列表 (Select/Radio 等) */
+    options?: any[];
+    /** 字段名 */
+    name?: string;
+    /** 是否为脏数据 */
+    isDirty?: boolean;
+    /** 是否被触摸过 */
+    isTouched?: boolean;
+    /** 子布局节点 (用于容器型 Widget) */
+    layoutChildren?: LayoutNode[];
+}
+
+export declare type WidgetRegistry = Record<string, default_2.ComponentType<any>>;
 
-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>;
-};
+/**
+ * Widget 渲染函数类型
+ * 接收 WidgetProps 和额外的 UI 属性
+ */
+export declare type WidgetRenderFn = React.ComponentType<WidgetProps & Record<string, any>>;
 
 export { }