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

package/dist/useDynamicFormState.d.cts

@@ -0,0 +1,749 @@
+import { i as ComponentLocale, r as ComponentFeedback } from "./config.cjs";
+import * as vue from "vue";
+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 * 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 = 编辑（回填已有数据 + 脏检查）
+ */
+type FormMode = 'create' | 'edit';
+/**
+ * 支持的布局类型
+ * @description 定义表单支持的所有布局模式
+ */
+type LayoutType = 'default' | 'inline' | 'grid' | 'card' | 'tabs' | 'steps' | 'dynamic' | 'custom';
+/**
+ * 标签位置类型
+ * @description 表单标签的显示位置
+ */
+type LabelPlacement = 'left' | 'top';
+/**
+ * 支持的表单控件类型
+ * @description 所有支持的表单输入控件类型
+ */
+type ComponentType = 'input' | 'textarea' | 'inputNumber' | 'select' | 'checkbox' | 'radio' | 'switch' | 'slider' | 'rate' | 'datePicker' | 'daterange' | 'timePicker' | 'cascader' | 'colorPicker' | 'upload' | 'editor';
+/**
+ * 选项项接口
+ * @description 用于 select、checkbox、radio 等组件的选项配置
+ */
+interface OptionItem {
+  value: string | number | boolean;
+  label: string;
+  disabled?: boolean;
+  [key: string]: unknown;
+}
+interface AsyncOptionsContext {
+  field: string;
+  reason: 'initialize' | 'dependency' | 'manual';
+  signal: AbortSignal;
+}
+interface FormErrorContext {
+  source: 'initialize' | 'async-options' | 'callback' | 'render' | 'submit';
+  field?: string;
+}
+/**
+ * 标签页配置接口
+ * @description 用于标签页布局的单个标签页配置
+ */
+interface TabConfig {
+  key: string;
+  title: string;
+  description?: string;
+  disabled?: boolean;
+  icon?: string;
+  closable?: boolean;
+}
+/**
+ * 步骤配置接口
+ * @description 用于步骤布局的单个步骤配置
+ */
+interface StepConfig {
+  key: string;
+  title: string;
+  description?: string;
+  disabled?: boolean;
+  icon?: string;
+  required?: boolean;
+}
+/**
+ * 分组配置接口
+ * @description 用于卡片布局和自定义布局的分组配置
+ */
+interface GroupConfig {
+  key: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  color?: string;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  defaultExpanded?: boolean;
+}
+/**
+ * 动态字段配置接口
+ * @description 用于动态布局的字段配置
+ */
+interface DynamicFieldConfig {
+  id: string;
+  type: ComponentType | string;
+  prop: string;
+  label: string;
+  visible: boolean;
+  removable: boolean;
+  created: number;
+  placeholder?: string;
+  layout?: {
+    span?: number;
+  };
+  rules?: FormItemRule[];
+}
+/**
+ * 表单项布局配置
+ * @description 单个表单项的布局相关配置
+ */
+interface ItemLayoutConfig {
+  span?: number;
+  offset?: number;
+  width?: string | number;
+  group?: string;
+  tab?: string;
+  step?: string;
+  dynamic?: boolean;
+  customRender?: boolean;
+  enhanced?: boolean;
+  class?: string;
+  style?: CSSProperties | Record<string, unknown>;
+  hidden?: boolean;
+}
+/**
+ * 网格布局配置
+ * @description 网格布局的详细配置选项
+ */
+interface GridLayoutConfig {
+  cols?: number;
+  gutter?: number;
+  yGutter?: number;
+  xGap?: number;
+  yGap?: number;
+}
+/**
+ * 内联布局配置
+ * @description 内联布局的详细配置选项
+ */
+interface InlineLayoutConfig {
+  gap?: number;
+  align?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
+  wrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+}
+/**
+ * 卡片布局配置
+ * @description 卡片布局的详细配置选项
+ */
+interface CardLayoutConfig {
+  groups?: GroupConfig[];
+  spacing?: number;
+  bordered?: boolean;
+}
+/**
+ * 标签页布局配置
+ * @description 标签页布局的详细配置选项
+ */
+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;
+}
+/**
+ * 步骤布局配置
+ * @description 步骤布局的详细配置选项
+ */
+interface StepsLayoutConfig {
+  steps?: StepConfig[];
+  vertical?: boolean;
+  size?: 'small' | 'medium';
+  defaultStep?: number;
+  showStepHeader?: boolean;
+  validateBeforeNext?: boolean;
+  prevButtonText?: string;
+  nextButtonText?: string;
+}
+/**
+ * 动态布局配置
+ * @description 动态布局的详细配置选项
+ */
+interface DynamicLayoutConfig {
+  grid?: {
+    cols?: number;
+    gutter?: number;
+  };
+  controls?: {
+    showControls?: boolean;
+    showItemControls?: boolean;
+    showStats?: boolean;
+  };
+  dynamic?: {
+    allowAdd?: boolean;
+    allowRemove?: boolean;
+    allowToggle?: boolean;
+    maxFields?: number;
+  };
+}
+/**
+ * 自定义渲染布局配置
+ * @description 自定义渲染布局的详细配置选项
+ */
+interface CustomLayoutConfig {
+  groups?: GroupConfig[];
+  rendering?: {
+    mode?: 'basic' | 'enhanced';
+    animations?: boolean;
+    tooltips?: boolean;
+  };
+  display?: {
+    showIntro?: boolean;
+    showModeSwitch?: boolean;
+    showGroupActions?: boolean;
+    showStats?: boolean;
+  };
+}
+/**
+ * 完整布局配置
+ * @description 包含所有布局类型的配置选项
+ */
+interface LayoutConfig {
+  type?: LayoutType;
+  grid?: GridLayoutConfig;
+  inline?: InlineLayoutConfig;
+  card?: CardLayoutConfig;
+  tabs?: TabsLayoutConfig;
+  steps?: StepsLayoutConfig;
+  dynamic?: DynamicLayoutConfig;
+  custom?: CustomLayoutConfig;
+}
+/**
+ * 表单配置项接口
+ * @description 单个表单项的完整配置
+ */
+interface FormOption<T extends object = FormRecord> {
+  id?: string;
+  type: ComponentType | string;
+  prop: FieldPath<T>;
+  label?: string;
+  value?: unknown;
+  placeholder?: string;
+  rules?: FormItemRule[];
+  attrs?: Record<string, unknown>;
+  children?: OptionItem[];
+  show?: boolean;
+  layout?: ItemLayoutConfig;
+  help?: string;
+  required?: boolean;
+  dependsOn?: FieldPath<T> | FieldPath<T>[];
+  showWhen?: (formModel: FormModel<T>) => boolean;
+  /** 字段级禁用（优先级高于全局 config.disabled） */
+  disabled?: boolean | ((formModel: FormModel<T>) => boolean);
+  /** 字段级只读（优先级高于全局 config.readonly） */
+  readonly?: boolean | ((formModel: FormModel<T>) => boolean);
+  /** 联动赋值：其他字段变化时自动计算本字段的值 */
+  valueWhen?: (formModel: FormModel<T>) => unknown;
+  /** 异步数据源：select / cascader / checkbox / radio 的远程选项加载 */
+  asyncOptions?: (formModel: FormModel<T>, context?: AsyncOptionsContext) => Promise<readonly OptionItem[]>;
+  /** 联动校验规则：根据表单数据动态返回校验规则 */
+  rulesWhen?: (formModel: FormModel<T>) => FormItemRule[];
+  /** 跨字段校验：需要引用多个字段值的验证函数，返回错误消息或 null */
+  crossFieldValidator?: (formModel: FormModel<T>) => MaybePromise<string | null>;
+}
+/**
+ * 表单提交事件参数
+ */
+interface SubmitEventPayload<T extends object = FormRecord> {
+  model: FormModel<T>;
+  form: FormInst;
+}
+/**
+ * C_Form 组件实例暴露的方法
+ * @description 表单组件实例对外暴露的所有方法
+ */
+interface FormInstance<T extends object = FormRecord> {
+  validate(): 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?: FieldPath<T> | FieldPath<T>[]): void;
+  getModel(): FormModel<T>;
+  setFields(fields: Partial<FormModel<T>>): void;
+  resetFields(): 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: FormModel<T>;
+  initialize(): void;
+  layoutType: ComputedRef<LayoutType>;
+  shouldShowDefaultActions: ComputedRef<boolean>;
+  /** 表单是否被修改过 */
+  isDirty: Ref<boolean>;
+  /** 获取被修改的字段列表 */
+  getChangedFields(): FieldPath<T>[];
+  /** 检查某字段是否被修改 */
+  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 extends object = FormRecord> = T;
+/**
+ * 渲染模式类型
+ */
+type RenderMode = 'basic' | 'enhanced';
+/**
+ * 动态表单配置接口
+ */
+interface DynamicFormConfig {
+  maxFields: number;
+  autoSave: boolean;
+  enableSort: boolean;
+  showControls: boolean;
+  showItemControls: boolean;
+}
+/**
+ * 动态表单状态接口
+ */
+interface DynamicFormState {
+  config: DynamicFormConfig;
+  baseFields: FormOption[];
+  dynamicFields: DynamicFieldConfig[];
+  hiddenFieldIds: Set<string>;
+  fieldCounter: number;
+  isInitialized: boolean;
+}
+/**
+ * 动态表单状态控制器
+ * @description 为组合式函数提供稳定的公共返回类型，避免声明文件泄漏依赖库内部类型
+ */
+interface DynamicFormController {
+  state: DeepReadonly<DynamicFormState>;
+  allFields: ComputedRef<FormOption[]>;
+  visibleFields: ComputedRef<FormOption[]>;
+  dynamicFieldsCount: ComputedRef<number>;
+  hiddenFieldsCount: ComputedRef<number>;
+  canAddMoreFields: ComputedRef<boolean>;
+  allVisible: ComputedRef<boolean>;
+  FIELD_TYPE_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: ComponentType;
+  }>;
+  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;
+}
+//#endregion
+//#region src/components/C_Form/composables/useFormConfig.d.ts
+/** 布局回调事件 — 替代原先 16 个 emit 中的纯透传事件 */
+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) => MaybePromise<boolean | void>;
+  onStepValidate?: (stepIndex: number) => void;
+  onFieldAdd?: (fieldConfig: DynamicFieldConfig) => void;
+  onFieldRemove?: (fieldId: string) => void;
+  onFieldToggle?: (fieldId: string, visible: boolean) => void;
+  onFieldsClear?: () => void;
+  onRenderModeChange?: (mode: RenderMode) => void;
+  onGroupToggle?: (groupKey: string, collapsed: boolean) => void;
+  onGroupReset?: (groupKey: string) => 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<T extends object = FormRecord> extends LayoutCallbacks<T> {
+  feedback?: ComponentFeedback;
+  locale?: ComponentLocale;
+  /** 布局类型，默认 'default' */
+  layout?: LayoutType;
+  /** 标签位置，默认 'left' */
+  labelPlacement?: LabelPlacement;
+  /** 标签宽度，默认 'auto' */
+  labelWidth?: string | number;
+  /** 尺寸，默认 'medium' */
+  size?: 'small' | 'medium' | 'large';
+  /** 禁用整个表单，默认 false */
+  disabled?: boolean;
+  /** 只读，默认 false */
+  readonly?: boolean;
+  /** 显示默认提交/重置按钮，默认 true */
+  showActions?: boolean;
+  /** 值变化时自动校验，默认 false */
+  validateOnChange?: boolean;
+  /** 动态移除配置项后是否保留其模型值，默认 false */
+  preserveRemovedFields?: boolean;
+  /** 默认提交按钮文案 */
+  submitText?: string;
+  /** 默认重置按钮文案 */
+  resetText?: string;
+  /** 表单模式：create = 新建（默认），edit = 编辑（配合 initialValues 实现回填 + 脏检查） */
+  mode?: FormMode;
+  /** 编辑模式初始值：设置后自动作为脏检查基准 */
+  initialValues?: Partial<T>;
+  grid?: GridLayoutConfig;
+  inline?: InlineLayoutConfig;
+  card?: CardLayoutConfig;
+  tabs?: TabsLayoutConfig;
+  steps?: StepsLayoutConfig;
+  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' | 'feedback' | 'locale'>> {
+  grid?: GridLayoutConfig;
+  inline?: InlineLayoutConfig;
+  card?: CardLayoutConfig;
+  tabs?: TabsLayoutConfig;
+  steps?: StepsLayoutConfig;
+  dynamic?: DynamicLayoutConfig;
+  custom?: CustomLayoutConfig;
+  onTabChange?: LayoutCallbacks['onTabChange'];
+  onTabBeforeChange?: LayoutCallbacks['onTabBeforeChange'];
+  onTabValidate?: LayoutCallbacks['onTabValidate'];
+  onStepChange?: LayoutCallbacks['onStepChange'];
+  onStepBeforeChange?: LayoutCallbacks['onStepBeforeChange'];
+  onStepValidate?: LayoutCallbacks['onStepValidate'];
+  onFieldAdd?: LayoutCallbacks['onFieldAdd'];
+  onFieldRemove?: LayoutCallbacks['onFieldRemove'];
+  onFieldToggle?: LayoutCallbacks['onFieldToggle'];
+  onFieldsClear?: LayoutCallbacks['onFieldsClear'];
+  onRenderModeChange?: LayoutCallbacks['onRenderModeChange'];
+  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;
+/** 拥有自身控制按钮的布局（不显示默认操作按钮） */
+declare const LAYOUTS_WITH_OWN_CONTROLS: readonly LayoutType[];
+/**
+ * 解析 FormConfig，合并默认值
+ * @param config - 用户传入的配置（可选）
+ * @returns 具有完整默认值的 ResolvedFormConfig
+ */
+declare function resolveFormConfig(config?: FormConfig): ResolvedFormConfig;
+/**
+ * 计算是否显示默认操作按钮
+ * @param resolved - 已解析的配置
+ */
+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 {
+  /** 字段配置数组 */
+  options: FormOption[];
+  /** 双向绑定表单数据 */
+  modelValue?: FormModel;
+  /** 统一配置对象（收拢原先 13 个分散 Props） */
+  config?: FormConfig;
+  /** 当前表单实例的自定义渲染器，不污染全局注册表 */
+  renderers?: Record<string, FormRenderer>;
+}
+declare var __VLS_33: {
+  form: {
+    validate: naive_ui_es_form_src_interface0.FormValidate;
+    restoreValidation: () => void;
+    invalidateLabelWidth: () => void;
+  } | null;
+  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_33) => any;
+};
+declare const __VLS_base: vue.DefineComponent<CFormProps, {
+  validate: () => Promise<void>;
+  validateField: (field: string | string[]) => 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: () => FormModel;
+  setFields: (fields: FormModel) => void;
+  resetFields: () => void;
+  setFieldValue: (field: string, value: unknown, shouldValidate?: boolean) => Promise<void>;
+  getFieldValue: (field: string) => unknown;
+  setFieldsValue: (fields: FormModel, shouldValidate?: boolean) => Promise<void>;
+  formRef: vue.Ref<{
+    validate: naive_ui_es_form_src_interface0.FormValidate;
+    restoreValidation: () => void;
+    invalidateLabelWidth: () => void;
+  } | null, FormInst | {
+    validate: naive_ui_es_form_src_interface0.FormValidate;
+    restoreValidation: () => void;
+    invalidateLabelWidth: () => void;
+  } | null>;
+  formModel: FormRecord;
+  initialize: () => void;
+  layoutType: vue.ComputedRef<LayoutType>;
+  shouldShowDefaultActions: vue.ComputedRef<boolean>;
+  isDirty: vue.Ref<boolean, boolean>;
+  getChangedFields: () => string[];
+  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: FormRecord) => any;
+  submit: (payload: SubmitEventPayload<FormRecord>) => any;
+  "validate-success": (model: FormRecord) => any;
+  "validate-error": (errors: unknown) => any;
+}, string, vue.PublicProps, Readonly<CFormProps> & Readonly<{
+  "onUpdate:modelValue"?: ((model: FormRecord) => any) | undefined;
+  onSubmit?: ((payload: SubmitEventPayload<FormRecord>) => any) | undefined;
+  "onValidate-success"?: ((model: FormRecord) => any) | undefined;
+  "onValidate-error"?: ((errors: unknown) => any) | undefined;
+}>, {
+  config: FormConfig;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#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
+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<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>;
+  validateTab: (tabKey: string) => Promise<boolean>;
+  validateDynamicFields: () => Promise<boolean>;
+  validateCustomGroup: (groupKey: string) => Promise<boolean>;
+  clearValidation: (field?: string | string[]) => void;
+  getModel: () => FormModel;
+  setFields: (fields: FormModel) => void;
+  resetFields: () => void;
+  setFieldValue: (field: string, value: unknown, shouldValidate?: boolean) => Promise<void>;
+  getFieldValue: (field: string) => unknown;
+  setFieldsValue: (fields: FormModel, shouldValidate?: boolean) => 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>>;
+  asyncErrorMap: Ref<Record<string, unknown>, Record<string, unknown>>;
+  reloadOptions: (field?: string) => Promise<void>;
+};
+//#endregion
+//#region src/components/C_Form/composables/useFormDirty.d.ts
+interface UseFormDirtyReturn {
+  /** 表单是否已修改 */
+  isDirty: Ref<boolean>;
+  /** 获取发生变化的字段名列表 */
+  getChangedFields: () => string[];
+  /** 检查指定字段是否脏 */
+  isFieldDirty: (field: string) => boolean;
+  /** 保存当前值为干净快照 */
+  markAsClean: () => void;
+  /** 获取干净快照的独立副本 */
+  getCleanModel: () => FormModel;
+}
+/**
+ * 脏检查 Composable — 追踪 formModel 相对于初始快照的变化
+ * @param formModel 响应式表单数据对象（reactive）
+ */
+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: 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 包含状态和方法的对象
+ */
+declare const useDynamicFormState: () => DynamicFormController;
+/**
+ * @description 动态表单状态类型
+ */
+type DynamicFormStateType = DynamicFormController;
+/**
+ * @description 动态表单状态注入键
+ */
+declare const DYNAMIC_FORM_STATE_KEY: unique symbol;
+//#endregion
+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 };