@robot-admin/naive-ui-components 0.10.3 → 0.11.1

package/dist/useDynamicFormState.d.ts

@@ -1,11 +1,18 @@
+import { i as ComponentLocale, r as ComponentFeedback } from "./config.js";
 import * as vue from "vue";
-import { CSSProperties, Component, ComputedRef, DeepReadonly, Ref, VNode } from "vue";
-import { FieldRule } from "@robot-admin/form-validate";
-import { FormInst } from "naive-ui/es";
+import { CSSProperties, Component, ComputedRef, DeepReadonly, InjectionKey, MaybeRefOrGetter, Ref, Slots, VNode } from "vue";
+import { FormInst, FormItemInst, FormItemRule, FormRules } from "naive-ui";
 import * as naive_ui_es_form_src_interface0 from "naive-ui/es/form/src/interface";
-import { FormInst as FormInst$1, FormRules } from "naive-ui/es/form";
+import * as _vue_shared0 from "@vue/shared";
 
 //#region src/components/C_Form/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type FormRecord = Record<string, unknown>;
+type AtomicFormValue = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | File | Blob;
+type NestedFieldPath<T extends object> = { [K in Extract<keyof T, string>]: NonNullable<T[K]> extends AtomicFormValue ? K : NonNullable<T[K]> extends readonly (infer Item)[] ? NonNullable<Item> extends AtomicFormValue ? K | `${K}.${number}` : NonNullable<Item> extends object ? K | `${K}.${number}` | `${K}.${number}.${NestedFieldPath<NonNullable<Item>>}` : K : NonNullable<T[K]> extends object ? K | `${K}.${NestedFieldPath<NonNullable<T[K]>>}` : K }[Extract<keyof T, string>];
+type FieldPath<T extends object = FormRecord> = string extends keyof T ? string : NestedFieldPath<T>;
+type NestedFieldPathValue<T, P extends string> = T extends readonly (infer Item)[] ? P extends `${number}.${infer Rest}` ? NestedFieldPathValue<NonNullable<Item>, Rest> : P extends `${number}` ? Item : unknown : P extends keyof T ? T[P] : P extends `${infer K}.${infer Rest}` ? K extends keyof T ? NestedFieldPathValue<NonNullable<T[K]>, Rest> : unknown : unknown;
+type FieldPathValue<T extends object, P extends string> = NestedFieldPathValue<T, P>;
 /**
  * 表单模式
  * @description create = 新建（空白表单），edit = 编辑（回填已有数据 + 脏检查）
@@ -34,7 +41,16 @@ interface OptionItem {
   value: string | number | boolean;
   label: string;
   disabled?: boolean;
-  [key: string]: any;
+  [key: string]: unknown;
+}
+interface AsyncOptionsContext {
+  field: string;
+  reason: 'initialize' | 'dependency' | 'manual';
+  signal: AbortSignal;
+}
+interface FormErrorContext {
+  source: 'initialize' | 'async-options' | 'callback' | 'render' | 'submit';
+  field?: string;
 }
 /**
  * 标签页配置接口
@@ -46,6 +62,7 @@ interface TabConfig {
   description?: string;
   disabled?: boolean;
   icon?: string;
+  closable?: boolean;
 }
 /**
  * 步骤配置接口
@@ -89,7 +106,7 @@ interface DynamicFieldConfig {
   layout?: {
     span?: number;
   };
-  rules?: FieldRule[];
+  rules?: FormItemRule[];
 }
 /**
  * 表单项布局配置
@@ -106,7 +123,7 @@ interface ItemLayoutConfig {
   customRender?: boolean;
   enhanced?: boolean;
   class?: string;
-  style?: CSSProperties | Record<string, any>;
+  style?: CSSProperties | Record<string, unknown>;
   hidden?: boolean;
 }
 /**
@@ -144,8 +161,17 @@ interface CardLayoutConfig {
  */
 interface TabsLayoutConfig {
   tabs?: TabConfig[];
+  type?: 'line' | 'card' | 'segment';
+  size?: 'small' | 'medium' | 'large';
   placement?: 'top' | 'right' | 'bottom' | 'left';
   defaultTab?: string;
+  animated?: boolean;
+  closable?: boolean;
+  addable?: boolean;
+  showTabHeader?: boolean;
+  showActions?: boolean;
+  showCount?: boolean;
+  validateBeforeSwitch?: boolean;
 }
 /**
  * 步骤布局配置
@@ -218,80 +244,88 @@ interface LayoutConfig {
  * 表单配置项接口
  * @description 单个表单项的完整配置
  */
-interface FormOption {
+interface FormOption<T extends object = FormRecord> {
   id?: string;
   type: ComponentType | string;
-  prop: string;
+  prop: FieldPath<T>;
   label?: string;
-  value?: any;
+  value?: unknown;
   placeholder?: string;
-  rules?: FieldRule[];
-  attrs?: Record<string, any>;
+  rules?: FormItemRule[];
+  attrs?: Record<string, unknown>;
   children?: OptionItem[];
   show?: boolean;
   layout?: ItemLayoutConfig;
   help?: string;
   required?: boolean;
-  dependsOn?: string | string[];
-  showWhen?: (formModel: Record<string, any>) => boolean;
+  dependsOn?: FieldPath<T> | FieldPath<T>[];
+  showWhen?: (formModel: FormModel<T>) => boolean;
   /** 字段级禁用（优先级高于全局 config.disabled） */
-  disabled?: boolean | ((formModel: Record<string, any>) => boolean);
+  disabled?: boolean | ((formModel: FormModel<T>) => boolean);
   /** 字段级只读（优先级高于全局 config.readonly） */
-  readonly?: boolean | ((formModel: Record<string, any>) => boolean);
+  readonly?: boolean | ((formModel: FormModel<T>) => boolean);
   /** 联动赋值：其他字段变化时自动计算本字段的值 */
-  valueWhen?: (formModel: Record<string, any>) => any;
+  valueWhen?: (formModel: FormModel<T>) => unknown;
   /** 异步数据源：select / cascader / checkbox / radio 的远程选项加载 */
-  asyncOptions?: (formModel: Record<string, any>) => Promise<OptionItem[]>;
+  asyncOptions?: (formModel: FormModel<T>, context?: AsyncOptionsContext) => Promise<readonly OptionItem[]>;
   /** 联动校验规则：根据表单数据动态返回校验规则 */
-  rulesWhen?: (formModel: Record<string, any>) => FieldRule[];
+  rulesWhen?: (formModel: FormModel<T>) => FormItemRule[];
   /** 跨字段校验：需要引用多个字段值的验证函数，返回错误消息或 null */
-  crossFieldValidator?: (formModel: Record<string, any>) => string | null;
+  crossFieldValidator?: (formModel: FormModel<T>) => MaybePromise<string | null>;
 }
 /**
  * 表单提交事件参数
  */
-interface SubmitEventPayload {
-  model: Record<string, any>;
+interface SubmitEventPayload<T extends object = FormRecord> {
+  model: FormModel<T>;
   form: FormInst;
 }
 /**
  * C_Form 组件实例暴露的方法
  * @description 表单组件实例对外暴露的所有方法
  */
-interface FormInstance {
+interface FormInstance<T extends object = FormRecord> {
   validate(): Promise<void>;
-  validateField(field: string | string[]): Promise<void>;
+  validateField(field: FieldPath<T> | FieldPath<T>[]): Promise<void>;
   validateStep(stepIndex: number): Promise<boolean>;
   validateTab(tabKey: string): Promise<boolean>;
   validateDynamicFields(): Promise<boolean>;
   validateCustomGroup(groupKey: string): Promise<boolean>;
-  clearValidation(field?: string | string[]): void;
-  getModel(): Record<string, any>;
-  setFields(fields: Record<string, any>): void;
+  clearValidation(field?: FieldPath<T> | FieldPath<T>[]): void;
+  getModel(): FormModel<T>;
+  setFields(fields: Partial<FormModel<T>>): void;
   resetFields(): void;
-  setFieldValue(field: string, value: any, shouldValidate?: boolean): Promise<void>;
-  getFieldValue(field: string): any;
-  setFieldsValue(fields: Record<string, any>, shouldValidate?: boolean): Promise<void>;
+  setFieldValue<P extends FieldPath<T>>(field: P, value: FieldPathValue<T, P>, shouldValidate?: boolean): Promise<void>;
+  getFieldValue<P extends FieldPath<T>>(field: P): FieldPathValue<T, P>;
+  setFieldsValue(fields: Partial<FormModel<T>>, shouldValidate?: boolean): Promise<void>;
   formRef: FormInst | null;
-  formModel: Record<string, any>;
+  formModel: FormModel<T>;
   initialize(): void;
   layoutType: ComputedRef<LayoutType>;
   shouldShowDefaultActions: ComputedRef<boolean>;
   /** 表单是否被修改过 */
   isDirty: Ref<boolean>;
   /** 获取被修改的字段列表 */
-  getChangedFields(): string[];
+  getChangedFields(): FieldPath<T>[];
   /** 检查某字段是否被修改 */
-  isFieldDirty(field: string): boolean;
+  isFieldDirty(field: FieldPath<T>): boolean;
   /** 将当前值设为初始快照（常用于编辑模式加载数据后） */
   markAsClean(): void;
   /** 字段异步选项的 loading 状态 */
   asyncLoadingMap: Ref<Record<string, boolean>>;
+  /** 字段异步选项加载错误 */
+  asyncErrorMap: Ref<Record<string, unknown>>;
+  /** 重新加载全部或指定字段的异步选项 */
+  reloadOptions(field?: FieldPath<T>): Promise<void>;
+  /** 是否正在提交 */
+  isSubmitting: Ref<boolean>;
+  /** 验证并提交，成功返回 true */
+  submit(): Promise<boolean>;
 }
 /**
  * 表单数据模型类型（泛型）
  */
-type FormModel<T = Record<string, any>> = T;
+type FormModel<T extends object = FormRecord> = T;
 /**
  * 渲染模式类型
  */
@@ -333,11 +367,11 @@ interface DynamicFormController {
     label: string;
     value: ComponentType;
   }>;
-  addField(config?: Partial<DynamicFieldConfig>): void;
-  removeField(index?: number): void;
-  clearDynamicFields(): void;
-  toggleFieldVisibility(fieldId: string): void;
-  toggleAllVisibility(): void;
+  addField(config?: Partial<DynamicFieldConfig>): DynamicFieldConfig | null;
+  removeField(index?: number): DynamicFieldConfig | null;
+  clearDynamicFields(): number;
+  toggleFieldVisibility(fieldId: string): boolean;
+  toggleAllVisibility(): boolean;
   updateConfig(config: Partial<DynamicFormConfig>): void;
   exportConfig(): string;
   initialize(baseFields: FormOption[], config?: Partial<DynamicFormConfig>): void;
@@ -345,11 +379,12 @@ interface DynamicFormController {
 //#endregion
 //#region src/components/C_Form/composables/useFormConfig.d.ts
 /** 布局回调事件 — 替代原先 16 个 emit 中的纯透传事件 */
-interface LayoutCallbacks {
+interface LayoutCallbacks<T extends object = FormRecord> {
   onTabChange?: (tabKey: string, tabIndex: number) => void;
+  onTabBeforeChange?: (currentTab: string, targetTab: string) => MaybePromise<boolean | void>;
   onTabValidate?: (tabKey: string) => void;
   onStepChange?: (stepIndex: number, stepKey: string) => void;
-  onStepBeforeChange?: (currentStep: number, targetStep: number) => void;
+  onStepBeforeChange?: (currentStep: number, targetStep: number) => MaybePromise<boolean | void>;
   onStepValidate?: (stepIndex: number) => void;
   onFieldAdd?: (fieldConfig: DynamicFieldConfig) => void;
   onFieldRemove?: (fieldId: string) => void;
@@ -358,14 +393,18 @@ interface LayoutCallbacks {
   onRenderModeChange?: (mode: RenderMode) => void;
   onGroupToggle?: (groupKey: string, collapsed: boolean) => void;
   onGroupReset?: (groupKey: string) => void;
-  onFieldsChange?: (fields: FormOption[]) => void;
+  onFieldsChange?: (fields: FormOption<T>[]) => void;
+  onSubmit?: (payload: SubmitEventPayload<T>) => MaybePromise<void>;
+  onError?: (error: unknown, context: FormErrorContext) => void;
 }
 /**
  * C_Form 统一配置接口
  * @description 收拢原先 13 个分散 Props 为 1 个 config 对象
  * 默认值均在 FORM_DEFAULTS 中集中管理
  */
-interface FormConfig extends LayoutCallbacks {
+interface FormConfig<T extends object = FormRecord> extends LayoutCallbacks<T> {
+  feedback?: ComponentFeedback;
+  locale?: ComponentLocale;
   /** 布局类型，默认 'default' */
   layout?: LayoutType;
   /** 标签位置，默认 'left' */
@@ -382,10 +421,16 @@ interface FormConfig extends LayoutCallbacks {
   showActions?: boolean;
   /** 值变化时自动校验，默认 false */
   validateOnChange?: boolean;
+  /** 动态移除配置项后是否保留其模型值，默认 false */
+  preserveRemovedFields?: boolean;
+  /** 默认提交按钮文案 */
+  submitText?: string;
+  /** 默认重置按钮文案 */
+  resetText?: string;
   /** 表单模式：create = 新建（默认），edit = 编辑（配合 initialValues 实现回填 + 脏检查） */
   mode?: FormMode;
   /** 编辑模式初始值：设置后自动作为脏检查基准 */
-  initialValues?: Record<string, any>;
+  initialValues?: Partial<T>;
   grid?: GridLayoutConfig;
   inline?: InlineLayoutConfig;
   card?: CardLayoutConfig;
@@ -394,8 +439,14 @@ interface FormConfig extends LayoutCallbacks {
   dynamic?: DynamicLayoutConfig;
   custom?: CustomLayoutConfig;
 }
+/** Application-level C_Form defaults injection key. */
+declare const FORM_GLOBAL_CONFIG_KEY: InjectionKey<FormConfig>;
+/** Read application-level C_Form defaults without requiring a provider. */
+declare function useFormGlobalConfig(): FormConfig;
+/** Merge nested layout sections while preserving local-over-global precedence. */
+declare function mergeFormConfig(local: FormConfig | undefined, global: FormConfig): FormConfig;
 /** 解析后的配置（所有必填字段均已设置默认值） */
-interface ResolvedFormConfig extends Required<Omit<FormConfig, keyof LayoutCallbacks | 'grid' | 'inline' | 'card' | 'tabs' | 'steps' | 'dynamic' | 'custom' | 'initialValues'>> {
+interface ResolvedFormConfig extends Required<Omit<FormConfig, keyof LayoutCallbacks | 'grid' | 'inline' | 'card' | 'tabs' | 'steps' | 'dynamic' | 'custom' | 'initialValues' | 'feedback' | 'locale'>> {
   grid?: GridLayoutConfig;
   inline?: InlineLayoutConfig;
   card?: CardLayoutConfig;
@@ -404,6 +455,7 @@ interface ResolvedFormConfig extends Required<Omit<FormConfig, keyof LayoutCallb
   dynamic?: DynamicLayoutConfig;
   custom?: CustomLayoutConfig;
   onTabChange?: LayoutCallbacks['onTabChange'];
+  onTabBeforeChange?: LayoutCallbacks['onTabBeforeChange'];
   onTabValidate?: LayoutCallbacks['onTabValidate'];
   onStepChange?: LayoutCallbacks['onStepChange'];
   onStepBeforeChange?: LayoutCallbacks['onStepBeforeChange'];
@@ -416,7 +468,11 @@ interface ResolvedFormConfig extends Required<Omit<FormConfig, keyof LayoutCallb
   onGroupToggle?: LayoutCallbacks['onGroupToggle'];
   onGroupReset?: LayoutCallbacks['onGroupReset'];
   onFieldsChange?: LayoutCallbacks['onFieldsChange'];
+  onSubmit?: LayoutCallbacks['onSubmit'];
+  onError?: LayoutCallbacks['onError'];
   initialValues?: Record<string, any>;
+  feedback?: ComponentFeedback;
+  locale?: ComponentLocale;
 }
 declare const FORM_DEFAULTS: ResolvedFormConfig;
 /** 拥有自身控制按钮的布局（不显示默认操作按钮） */
@@ -433,6 +489,52 @@ declare function resolveFormConfig(config?: FormConfig): ResolvedFormConfig;
  */
 declare function shouldShowActions(resolved: ResolvedFormConfig): boolean;
 //#endregion
+//#region src/components/C_Form/composables/useFormRenderer.d.ts
+type ComponentMap = Record<string, Component>;
+type RendererProps = Record<string, unknown> & {
+  'onUpdate:value'?: (value: unknown) => void;
+};
+interface FormRendererContext {
+  slots?: Readonly<Slots>;
+  components: ComponentMap;
+}
+type FormRenderer = (baseProps: RendererProps, item: FormOption, config: ResolvedFormConfig, context: FormRendererContext) => VNode | null;
+interface UseFormRendererOptions {
+  formModel: FormModel;
+  visibleOptions: ComputedRef<FormOption[]>;
+  config: ComputedRef<ResolvedFormConfig>;
+  handleFieldChange: (field: string) => void;
+  componentMap: ComponentMap;
+  instanceSlots?: Readonly<Slots>;
+  asyncOptionsCache: Ref<Record<string, OptionItem[]>>;
+  asyncLoadingMap: Ref<Record<string, boolean>>;
+  renderers?: ComputedRef<Record<string, FormRenderer> | undefined>;
+  setFormItemRef?: (field: string, instance: FormItemInst | null) => void;
+  onError?: (error: unknown, field: string) => void;
+}
+/**
+ * 运行时注册自定义渲染器 — 开闭原则
+ */
+declare function registerRenderer(type: string, renderer: FormRenderer): () => boolean;
+/** Remove a global renderer. Passing the renderer prevents deleting a newer registration. */
+declare function unregisterRenderer(type: string, renderer?: FormRenderer): boolean;
+/**
+ * 渲染引擎 Composable — 生成 formItems VNode 数组
+ *
+ * v0.8.0 增强：
+ * - 字段级 disabled / readonly
+ * - help / tooltip label 渲染
+ * - asyncOptions 远程选项合并
+ * - loading 占位
+ */
+declare function useFormRenderer(opts: UseFormRendererOptions): {
+  renderFormItem: (item: FormOption) => VNode | null;
+  formItems: ComputedRef<VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  getBaseProps: (item: FormOption) => RendererProps;
+};
+//#endregion
 //#region src/components/C_Form/index.vue.d.ts
 interface CFormProps {
   /** 字段配置数组 */
@@ -441,22 +543,28 @@ interface CFormProps {
   modelValue?: FormModel;
   /** 统一配置对象（收拢原先 13 个分散 Props） */
   config?: FormConfig;
+  /** 当前表单实例的自定义渲染器，不污染全局注册表 */
+  renderers?: Record<string, FormRenderer>;
 }
-declare var __VLS_36: {
+declare var __VLS_33: {
   form: {
     validate: naive_ui_es_form_src_interface0.FormValidate;
     restoreValidation: () => void;
+    invalidateLabelWidth: () => void;
   } | null;
-  model: Record<string, any>;
+  model: FormRecord;
   validate: () => Promise<void>;
   validateField: (field: string | string[]) => Promise<void>;
   reset: () => void;
   setFields: (fields: FormModel) => void;
   getModel: () => FormModel;
   clearValidation: (field?: string | string[]) => void;
+  submit: () => Promise<boolean>;
+  reloadOptions: (field?: string) => Promise<void>;
+  submitting: boolean;
 };
 type __VLS_Slots = {} & {
-  action?: (props: typeof __VLS_36) => any;
+  action?: (props: typeof __VLS_33) => any;
 };
 declare const __VLS_base: vue.DefineComponent<CFormProps, {
   validate: () => Promise<void>;
@@ -475,11 +583,13 @@ declare const __VLS_base: vue.DefineComponent<CFormProps, {
   formRef: vue.Ref<{
     validate: naive_ui_es_form_src_interface0.FormValidate;
     restoreValidation: () => void;
-  } | null, FormInst$1 | {
+    invalidateLabelWidth: () => void;
+  } | null, FormInst | {
     validate: naive_ui_es_form_src_interface0.FormValidate;
     restoreValidation: () => void;
+    invalidateLabelWidth: () => void;
   } | null>;
-  formModel: Record<string, any>;
+  formModel: FormRecord;
   initialize: () => void;
   layoutType: vue.ComputedRef<LayoutType>;
   shouldShowDefaultActions: vue.ComputedRef<boolean>;
@@ -488,16 +598,20 @@ declare const __VLS_base: vue.DefineComponent<CFormProps, {
   isFieldDirty: (field: string) => boolean;
   markAsClean: () => void;
   asyncLoadingMap: vue.Ref<Record<string, boolean>, Record<string, boolean>>;
+  asyncErrorMap: vue.Ref<Record<string, unknown>, Record<string, unknown>>;
+  reloadOptions: (field?: string) => Promise<void>;
+  isSubmitting: vue.Ref<boolean, boolean>;
+  submit: () => Promise<boolean>;
 }, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
-  "update:modelValue": (model: Record<string, any>) => any;
+  "update:modelValue": (model: FormRecord) => any;
+  submit: (payload: SubmitEventPayload<FormRecord>) => any;
+  "validate-success": (model: FormRecord) => any;
   "validate-error": (errors: unknown) => any;
-  submit: (payload: SubmitEventPayload) => any;
-  "validate-success": (model: Record<string, any>) => any;
 }, string, vue.PublicProps, Readonly<CFormProps> & Readonly<{
-  "onUpdate:modelValue"?: ((model: Record<string, any>) => any) | undefined;
+  "onUpdate:modelValue"?: ((model: FormRecord) => any) | undefined;
+  onSubmit?: ((payload: SubmitEventPayload<FormRecord>) => any) | undefined;
+  "onValidate-success"?: ((model: FormRecord) => any) | undefined;
   "onValidate-error"?: ((errors: unknown) => any) | undefined;
-  onSubmit?: ((payload: SubmitEventPayload) => any) | undefined;
-  "onValidate-success"?: ((model: Record<string, any>) => any) | undefined;
 }>, {
   config: FormConfig;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
@@ -509,21 +623,46 @@ type __VLS_WithSlots<T, S> = T & {
   };
 };
 //#endregion
+//#region src/components/C_Form/helpers.d.ts
+/** Preserve business-model field inference without changing the component API. */
+declare function defineFormOptions<T extends object = FormRecord>(options: FormOption<T>[]): FormOption<T>[];
+/** Type-safe identity helper for reusable form configuration. */
+declare function defineFormConfig<T extends object = FormRecord>(config: FormConfig<T>): FormConfig<T>;
+interface UseCFormOptions<T extends object> {
+  initialValues: T;
+  options: MaybeRefOrGetter<FormOption<T>[]>;
+  config?: MaybeRefOrGetter<FormConfig<T> | undefined>;
+}
+/** Small binding helper for the common controlled C_Form setup. */
+declare function useCForm<T extends object>(setup: UseCFormOptions<T>): {
+  model: vue.Ref<any, any> extends T ? T extends T & vue.Ref<any, any> ? _vue_shared0.IfAny<T, vue.ShallowRef<T, T>, T> : vue.ShallowRef<T, T> : vue.ShallowRef<T, T>;
+  formRef: vue.ShallowRef<FormInstance<T> | null, FormInstance<T> | null>;
+  bindings: vue.ComputedRef<{
+    modelValue: any;
+    options: FormOption<T>[];
+    config: FormConfig<T> | undefined;
+    'onUpdate:modelValue': (value: FormModel<T>) => void;
+  }>;
+  validate: () => Promise<void>;
+  submit: () => Promise<boolean>;
+  reset: () => void | undefined;
+};
+//#endregion
 //#region src/components/C_Form/composables/useFormState.d.ts
-/**
- * C_Form 状态引擎 — 管理表单数据模型、校验规则、验证 API、字段操作、脏检查、联动
- */
-declare function useFormState(options: ComputedRef<FormOption[]>, config: ComputedRef<ResolvedFormConfig>, formRef: Ref<FormInst$1 | null>, emit: {
-  (e: 'update:modelValue', model: FormModel): void;
-  (e: 'validate-success', model: FormModel): void;
-  (e: 'validate-error', errors: unknown): void;
-  (e: 'submit', payload: SubmitEventPayload): void;
-}): {
-  formModel: Record<string, any>;
+type FormEmit = {
+  (event: 'update:modelValue', model: FormModel): void;
+  (event: 'validate-success', model: FormModel): void;
+  (event: 'validate-error', errors: unknown): void;
+  (event: 'submit', payload: SubmitEventPayload): void;
+};
+/** C_Form state, validation, async options and model synchronization engine. */
+declare function useFormState(options: ComputedRef<FormOption[]>, config: ComputedRef<ResolvedFormConfig>, formRef: Ref<FormInst | null>, emit: FormEmit, externalModel?: ComputedRef<FormModel | undefined>): {
+  formModel: FormRecord;
   formRules: FormRules;
-  visibleOptions: ComputedRef<FormOption[]>;
+  visibleOptions: ComputedRef<FormOption<FormRecord>[]>;
   initialize: () => void;
   handleFieldChange: (field: string) => void;
+  setFormItemRef: (field: string, instance: FormItemInst | null) => void;
   validate: () => Promise<void>;
   validateField: (field: string | string[]) => Promise<void>;
   validateStep: (stepIndex: number) => Promise<boolean>;
@@ -537,51 +676,18 @@ declare function useFormState(options: ComputedRef<FormOption[]>, config: Comput
   setFieldValue: (field: string, value: unknown, shouldValidate?: boolean) => Promise<void>;
   getFieldValue: (field: string) => unknown;
   setFieldsValue: (fields: FormModel, shouldValidate?: boolean) => Promise<void>;
-  handleSubmit: () => Promise<void>;
+  submit: () => Promise<boolean>;
+  handleSubmit: () => Promise<boolean>;
   handleReset: () => void;
+  isSubmitting: Ref<boolean, boolean>;
   isDirty: Ref<boolean, boolean>;
   getChangedFields: () => string[];
   isFieldDirty: (field: string) => boolean;
   markAsClean: () => void;
   asyncOptionsCache: Ref<Record<string, OptionItem[]>, Record<string, OptionItem[]>>;
   asyncLoadingMap: Ref<Record<string, boolean>, Record<string, boolean>>;
-};
-//#endregion
-//#region src/components/C_Form/composables/useFormRenderer.d.ts
-type ComponentMap = Record<string, Component>;
-type FormRenderer = (baseProps: Record<string, any>, item: FormOption, config: ResolvedFormConfig, ctx?: {
-  slots?: Record<string, any>;
-  components?: ComponentMap;
-}) => VNode | null;
-interface UseFormRendererOptions {
-  formModel: FormModel;
-  visibleOptions: ComputedRef<FormOption[]>;
-  config: ComputedRef<ResolvedFormConfig>;
-  handleFieldChange: (field: string) => void;
-  componentMap: ComponentMap;
-  instanceSlots?: Record<string, any>;
-  asyncOptionsCache: Ref<Record<string, OptionItem[]>>;
-  asyncLoadingMap: Ref<Record<string, boolean>>;
-}
-/**
- * 运行时注册自定义渲染器 — 开闭原则
- */
-declare function registerRenderer(type: string, renderer: FormRenderer): void;
-/**
- * 渲染引擎 Composable — 生成 formItems VNode 数组
- *
- * v0.8.0 增强：
- * - 字段级 disabled / readonly
- * - help / tooltip label 渲染
- * - asyncOptions 远程选项合并
- * - loading 占位
- */
-declare function useFormRenderer(opts: UseFormRendererOptions): {
-  renderFormItem: (item: FormOption) => VNode | null;
-  formItems: ComputedRef<VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-  }>[]>;
-  getBaseProps: (item: FormOption) => Record<string, unknown>;
+  asyncErrorMap: Ref<Record<string, unknown>, Record<string, unknown>>;
+  reloadOptions: (field?: string) => Promise<void>;
 };
 //#endregion
 //#region src/components/C_Form/composables/useFormDirty.d.ts
@@ -594,21 +700,38 @@ interface UseFormDirtyReturn {
   isFieldDirty: (field: string) => boolean;
   /** 保存当前值为干净快照 */
   markAsClean: () => void;
+  /** 获取干净快照的独立副本 */
+  getCleanModel: () => FormModel;
 }
 /**
  * 脏检查 Composable — 追踪 formModel 相对于初始快照的变化
  * @param formModel 响应式表单数据对象（reactive）
  */
-declare function useFormDirty(formModel: FormModel): UseFormDirtyReturn;
+declare function useFormDirty(formModel: FormModel, fields?: MaybeRefOrGetter<readonly string[]>): UseFormDirtyReturn;
 //#endregion
 //#region src/components/C_Form/composables/useDynamicFormState.d.ts
 /**
  * @description 可用的字段类型选项
  */
-declare const FIELD_TYPE_OPTIONS: {
-  label: string;
-  value: ComponentType;
-}[];
+declare const FIELD_TYPE_OPTIONS: readonly [{
+  readonly label: "文本输入";
+  readonly value: ComponentType;
+}, {
+  readonly label: "数字输入";
+  readonly value: ComponentType;
+}, {
+  readonly label: "多行文本";
+  readonly value: ComponentType;
+}, {
+  readonly label: "下拉选择";
+  readonly value: ComponentType;
+}, {
+  readonly label: "开关切换";
+  readonly value: ComponentType;
+}, {
+  readonly label: "评分组件";
+  readonly value: ComponentType;
+}];
 /**
  * @description 创建和管理动态表单状态
  * @returns 包含状态和方法的对象
@@ -623,5 +746,4 @@ type DynamicFormStateType = DynamicFormController;
  */
 declare const DYNAMIC_FORM_STATE_KEY: unique symbol;
 //#endregion
-export { FormModel as A, TabsLayoutConfig as B, CustomLayoutConfig as C, DynamicFormState as D, DynamicFormController as E, LayoutConfig as F, LayoutType as I, OptionItem as L, GridLayoutConfig as M, InlineLayoutConfig as N, FormInstance as O, LabelPlacement as P, StepsLayoutConfig as R, ComponentType as S, DynamicFormConfig as T, LayoutCallbacks as _, UseFormDirtyReturn as a, shouldShowActions as b, FormRenderer as c, useFormRenderer as d, useFormState as f, LAYOUTS_WITH_OWN_CONTROLS as g, FormConfig as h, useDynamicFormState as i, FormOption as j, FormMode as k, UseFormRendererOptions as l, FORM_DEFAULTS as m, DynamicFormStateType as n, useFormDirty as o, _default as p, FIELD_TYPE_OPTIONS as r, ComponentMap as s, DYNAMIC_FORM_STATE_KEY as t, registerRenderer as u, ResolvedFormConfig as v, DynamicFieldConfig as w, CardLayoutConfig as x, resolveFormConfig as y, SubmitEventPayload as z };
-//# sourceMappingURL=useDynamicFormState.d.ts.map
+export { OptionItem as $, useFormGlobalConfig as A, FieldPathValue as B, FormConfig as C, mergeFormConfig as D, ResolvedFormConfig as E, DynamicFieldConfig as F, FormOption as G, FormInstance as H, DynamicFormConfig as I, InlineLayoutConfig as J, FormRecord as K, DynamicFormController as L, CardLayoutConfig as M, ComponentType as N, resolveFormConfig as O, CustomLayoutConfig as P, MaybePromise as Q, DynamicFormState as R, FORM_GLOBAL_CONFIG_KEY as S, LayoutCallbacks as T, FormMode as U, FormErrorContext as V, FormModel as W, LayoutConfig as X, LabelPlacement as Y, LayoutType as Z, UseFormRendererOptions as _, UseFormDirtyReturn as a, useFormRenderer as b, UseCFormOptions as c, useCForm as d, StepsLayoutConfig as et, _default as f, RendererProps as g, FormRendererContext as h, useDynamicFormState as i, AsyncOptionsContext as j, shouldShowActions as k, defineFormConfig as l, FormRenderer as m, DynamicFormStateType as n, TabsLayoutConfig as nt, useFormDirty as o, ComponentMap as p, GridLayoutConfig as q, FIELD_TYPE_OPTIONS as r, useFormState as s, DYNAMIC_FORM_STATE_KEY as t, SubmitEventPayload as tt, defineFormOptions as u, registerRenderer as v, LAYOUTS_WITH_OWN_CONTROLS as w, FORM_DEFAULTS as x, unregisterRenderer as y, FieldPath as z };