@tmagic/form 1.8.0-manmanyu.9 → 1.8.1

package/types/headless.d.ts

@@ -0,0 +1,682 @@
+import { App, AppContext, Component, ComputedRef, InjectionKey, MaybeRef, Ref } from "vue";
+import { FormContext, FormItemConfig } from "@tmagic/form-schema";
+export * from "@tmagic/form-schema";
+declare namespace schema_d_exports {
+  export { ChangeRecord, ContainerChangeEventData, FORM_CONTEXT_KEY, FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY, FormDiffConfig, FormLabelSlotProps, FormSlots, ValidateError };
+}
+import * as import__tmagic_form_schema from "@tmagic/form-schema";
+/**
+ * 对比模式相关配置，由 `MForm` 通过 `provide` 注入，
+ * 所有层级的 Container（含嵌套在 fieldset / panel 等容器组件内部的 Container）通过 `inject` 获取，
+ * 无需逐层透传 prop。
+ */
+export interface FormDiffConfig {
+  /**
+   * 自定义"是否展示对比内容"的判断函数（仅在对比模式下生效）。
+   *
+   * - 不传：使用默认逻辑 `!isEqual(curValue, lastValue)`；
+   * - 传函数：完全以函数返回值为准，返回 `true` 才展示前后两份对比内容。
+   */
+  showDiff?: (_data: {
+    curValue: any;
+    lastValue: any;
+    config: FormItemConfig;
+  }) => boolean;
+  /**
+   * 自定义「自接管对比」的字段类型（仅在对比模式下生效）。
+   *
+   * - 传数组：在内置类型基础上「追加」这些类型；
+   * - 传函数：入参为内置类型数组，返回值作为「最终」完整类型列表（可完全替换内置项）。
+   */
+  selfDiffFieldTypes?: string[] | ((_defaultTypes: string[]) => string[]);
+}
+export declare const FORM_DIFF_CONFIG_KEY: InjectionKey<FormDiffConfig>;
+export declare const FORM_TYPE_MATCH_VALID_KEY: InjectionKey<ComputedRef<boolean>>;
+/**
+ * 宿主业务上下文，由 `MForm`（或更外层的 Editor）通过 `provide` 下发。
+ *
+ * 嵌套表单（Link 子表单、FormBox、临时校验表单等）会自动继承最近祖先的 context，
+ * 无需层层透传。
+ *
+ * 配置回调统一通过 `mForm.xxx` 读取，由 formState 的读穿 Proxy 落到这里。
+ */
+export declare const FORM_CONTEXT_KEY: InjectionKey<ComputedRef<FormContext>>;
+export interface ValidateError {
+  message: string;
+  field: string;
+}
+export interface ChangeRecord {
+  propPath?: string;
+  value: any;
+}
+export interface ContainerChangeEventData {
+  modifyKey?: string;
+  changeRecords?: ChangeRecord[];
+}
+/** 自定义 label slot 的作用域参数 */
+export interface FormLabelSlotProps {
+  /** 当前表单项配置 */
+  config: FormItemConfig;
+  /** 经处理后的类型 */
+  type: string;
+  /** 经 filterFunction 处理后的 label 文案 */
+  text?: string;
+  /** 完整字段路径（包含父级前缀） */
+  prop: string;
+  /** 经 filterFunction 处理后的最终禁用状态 */
+  disabled?: boolean;
+}
+/** Form / Container 暴露的具名 slot 定义 */
+export interface FormSlots {
+  label(_props: FormLabelSlotProps): any;
+}
+//#endregion
+//#region temp/packages/form/src/utils/formStateProxy.d.ts
+/**
+ * 按优先级分层合并上下文，**靠后的层优先**。
+ *
+ * 用读穿 Proxy 而非 `{ ...a, ...b }`：展开会立即执行 accessor，
+ * 而宿主允许用 `{ get stage() { ... } }` 这类读时求值的描述符。
+ */
+export declare const mergeFormContexts: (...layers: (schema_d_exports.FormContext | undefined | null)[]) => schema_d_exports.FormContext;
+/**
+ * 将 coreState 与宿主业务上下文关联：读取时优先 core，miss 再读穿到 context。
+ *
+ * - `get` 用属性访问而非 `Reflect.get(t, k, receiver)`，避免破坏 Vue reactive 的 `__v_raw`；
+ * - symbol 键一律只走 core，四个 trap 保持一致。context 是业务数据袋，不承载 symbol 键，
+ *   把 Vue / 工具链的内部 symbol 隔离在 core 上才能让 `toRaw` / `isReactive` 判定正确；
+ * - `ownKeys` + `getOwnPropertyDescriptor` 保证 `Object.entries(formState)` 能枚举到扩展字段
+ *   （admin-web-next 的 `pickPanelFormStateExtendFields` 依赖此语义）；
+ * - `set` 写入 coreState，第三方 `formState.xxx = v` 仍生效且优先于 context。
+ *
+ * 独立成文件，避免与 `form.ts` ↔ `typeMatch.ts` 形成循环依赖。
+ */
+export declare const createFormStateProxy: (coreState: schema_d_exports.FormState, getContext: (() => schema_d_exports.FormContext) | Ref<schema_d_exports.FormContext>) => schema_d_exports.FormState;
+//#endregion
+//#region temp/packages/form/src/utils/form.d.ts
+type AsyncValidatorFn = (rule: any, value: any, callback: Function, source?: any, options?: any) => any;
+/**
+ * 将 async-validator（Element Plus）风格的 validator 适配到当前 UI 库。
+ * TDesign 调用签名为 `(val) => boolean | CustomValidateObj | Promise`，无 callback。
+ */
+export declare const adaptFormValidator: (validator: AsyncValidatorFn) => AsyncValidatorFn;
+export declare const createValues: (mForm: schema_d_exports.FormState | undefined, config?: schema_d_exports.FormConfig | schema_d_exports.TabPaneConfig[], initValue?: schema_d_exports.FormValue, value?: schema_d_exports.FormValue) => schema_d_exports.FormValue;
+export declare const createFormStateBase: (ui?: {
+  $message?: any;
+  $messageBox?: any;
+}) => {
+  fields: Map<string, any>;
+  setField: (prop: string, field: any) => Map<string, any>;
+  getField: (prop: string) => any;
+  deleteField: (prop: string) => boolean;
+  $messageBox: any;
+  $message: any;
+  post: (options: any) => any;
+};
+/**
+ * 配置项的 `name` 是否可用于从 model 中下钻取值。
+ *
+ * 供 `Container.vue` 与无渲染校验（`collectValidatableFields`）共用，两者对「该不该下钻」
+ * 的判断必须一致。
+ */
+export declare const isValidName: (name: unknown) => boolean;
+/**
+ * 在 `prop` 后追加一段路径。
+ *
+ * 用于容器把 `prop` 透传给子级时再拼上索引 / key（如 group-list 的行、table 的行）。
+ */
+export declare const appendProp: (prop: string | undefined, key: string | number) => string;
+/**
+ * 由父级 `prop` 与配置项 `name` 拼出该配置项的完整 `prop`（即 FormItem 的 prop）。
+ *
+ * 调用方传入的 name 已按 `config.name || ''` 归一化，空 name 表示该配置项不占据值路径上的一层，
+ * 此时沿用父级 `prop`。
+ */
+export declare const getItemProp: (prop?: string | undefined, name?: string | number | undefined) => string;
+/**
+ * 归一化配置项的 `type`：求值动态 type、剥离容器语义的 type、驼峰转中划线、补默认值。
+ *
+ * 供 `Container.vue` 与无渲染校验共用，保证两者分派到的 type 完全一致。
+ */
+export declare const resolveItemType: (mForm: schema_d_exports.FormState | undefined, config: any, props: any) => string;
+export declare const filterFunction: <T = any>(mForm: schema_d_exports.FormState | undefined, config: T | schema_d_exports.FilterFunction<T> | undefined, props: any) => T | undefined;
+export declare const display: (mForm: schema_d_exports.FormState | undefined, config: any, props: any) => any;
+export declare const getRules: (mForm: schema_d_exports.FormState | undefined, r: (schema_d_exports.Rule[] | schema_d_exports.Rule) | undefined, props: any, typeMatchValid?: MaybeRef<boolean>) => schema_d_exports.Rule[];
+/**
+ * 与 `getRules` 相同，但 validator 保持 async-validator（Element Plus）原生签名，不做 UI 库适配。
+ *
+ * 供无渲染校验（`validateValues`）使用：它直接把规则交给 async-validator 执行，
+ * 不经过 TDesign 的 `validator(val)` 调用约定，因此不能套 `adaptFormValidator`。
+ */
+export declare const getNativeRules: (mForm: schema_d_exports.FormState | undefined, r: (schema_d_exports.Rule[] | schema_d_exports.Rule) | undefined, props: any, typeMatchValid?: MaybeRef<boolean>) => schema_d_exports.Rule[];
+export declare const initValue: (mForm: schema_d_exports.FormState | undefined, { initValues, config }: {
+  initValues: schema_d_exports.FormValue;
+  config: schema_d_exports.FormConfig;
+}) => Promise<schema_d_exports.FormValue>;
+export declare const datetimeFormatter: (v: string | Date, defaultValue?: string, format?: string) => string | number;
+export declare const getDataByPage: (data: any[] | undefined, pagecontext: number, pagesize: number) => any[];
+export declare const sortArray: (data: any[], newIndex: number, oldIndex: number, sortKey?: string) => any[];
+export declare const sortChange: (data: any[], { prop, order }: schema_d_exports.SortProp) => void;
+export declare const createObjectProp: (prop: string, key: string, name?: string | number) => string;
+//#endregion
+//#region temp/packages/form/src/utils/collectFields.d.ts
+/** 一个参与校验的字段：与渲染式校验中「一个带 rules 的 TMagicFormItem」一一对应 */
+interface CollectedField {
+  /** 字段的完整 prop 路径（从表单根 values 起算，与 FormItem 的 prop 一致） */
+  prop: string;
+  /** 经 `getNativeRules` 处理后的规则（validator 为 async-validator 原生签名） */
+  rules: schema_d_exports.Rule[];
+  /** 字段配置 */
+  config: schema_d_exports.FormItemConfig;
+  /** 字段所在层级的 model 切片 */
+  model: schema_d_exports.FormValue;
+}
+/** 已登记的 innerConfig 回调自身抛错时抛出（机制故障，不是漏登记） */
+export declare class FieldInnerConfigError extends Error {
+  readonly code = "FIELD_INNER_CONFIG";
+  readonly type: string;
+  readonly prop: string;
+  constructor(type: string, prop: string, cause: unknown);
+}
+export declare const isFieldInnerConfigError: (error: unknown) => error is FieldInnerConfigError;
+/**
+ * 遍历模式。同一套遍历规则服务两个用途，避免两条链路各写一份而产生偏差：
+ *
+ * - `collect`：收集带 rules 的字段，按 `display` 过滤（对应「渲染出来的 FormItem 集合」）；
+ * - `effects`：执行字段登记的值初始化写入，不收集字段，且不看 `display`
+ *   （`display: false` 的字段同样要规整；`type: 'hidden'` 在该节点停止，不往下分派）。
+ */
+type WalkMode = 'collect' | 'effects';
+interface WalkContext {
+  mForm: schema_d_exports.FormState | undefined;
+  /**
+   * 是否自动给字段注入 typeMatch 规则，对应 MForm 的 `typeMatchValid`。
+   *
+   * 只在 `collect` 模式下有用：`addField` 把它交给 `getNativeRules`。为 true 且字段
+   * rules 尚未显式声明 `typeMatch`（true / false）时，自动补一条 `{ typeMatch: true }`，
+   * 按字段 `type` 校验当前值形态是否合法（空值放行，必填仍靠 `required`）。
+   * 单字段可在 rules 里写 `typeMatch: false` 关闭自动注入。
+   *
+   * `effects` 模式不收集规则，无需传入。
+   */
+  typeMatchValid?: boolean;
+  fields: CollectedField[];
+  /** 本次遍历处理的表单值根对象（对比模式下为 lastValues 那一份） */
+  values: schema_d_exports.FormValue;
+  mode: WalkMode;
+}
+interface WalkNode {
+  config: schema_d_exports.FormItemConfig;
+  /** 所在层级的 model 切片（对应 Container 的 `props.model`） */
+  model: schema_d_exports.FormValue;
+  /** 父级 prop（对应 Container 的 `props.prop`） */
+  prop: string;
+}
+type ContainerWalker = (_ctx: WalkContext, _node: WalkNode, _itemProp: string) => void;
+/**
+ * 纯逻辑收集「一份 config + 一份 values」中所有参与校验的字段。
+ *
+ * 遍历规则与 `Container.vue` 及各容器组件的模板一一对应，因此产出的 prop / rules
+ * 与渲染式校验（挂载 MForm 后调用 `validate()`）等价，无需任何 DOM 或组件实例。
+ *
+ * 本函数只读不写。字段的值初始化副作用由 `applyMountValueEffects` 负责，
+ * 调用方需在初始化表单值之后、收集字段之前执行一次（`validateValues` 已经这么做）。
+ *
+ * @param mForm - 表单状态；无渲染时由 `createHeadlessFormState` 构造
+ * @param config - 表单配置
+ * @param values - 表单值
+ * @param [typeMatchValid] - 是否自动注入 typeMatch 规则；为 true 时，未显式声明
+ *   `typeMatch` 的字段会补上 `{ typeMatch: true }`，按字段 type 校验值形态
+ * @returns 带规则的字段列表
+ */
+export declare const collectValidatableFields: (mForm: schema_d_exports.FormState | undefined, config: schema_d_exports.FormConfig, values: schema_d_exports.FormValue, typeMatchValid?: boolean) => CollectedField[];
+/**
+ * 执行「一份 config + 一份 values」中所有叶子字段登记的值初始化写入，就地改写 `values`。
+ *
+ * 渲染与无渲染两条链路共用的唯一执行点：字段组件自身不再在 setup 里改写 model，
+ * 由持有完整表单值的一方（`Form.vue` / `validateValues`）在表单值初始化完成、
+ * 且已挂到 `mForm.values` 之后调用一次。这样 effect 与动态 `type` 回调读到的
+ * `formValue` 就是最新值，而不是上一轮的旧值。
+ *
+ * 与 `collectValidatableFields` 的差异：不看 `display`（`display: false` 的字段也会规整）。
+ * `type: 'hidden'` 会在该节点停止遍历，内部字段不执行 effect。
+ *
+ * `prop` 与 `values` 都以传入的 `values` 为根，因此也可以用于 tab / table 新增行这类
+ * 「先构造一份子树的值，再挂到表单上」的场景：传入子树配置与该行的值即可。
+ *
+ * @param mForm - 表单状态；无渲染时由 `createHeadlessFormState` 构造
+ * @param config - 表单配置
+ * @param values - 表单值（会被就地修改）
+ */
+export declare const applyMountValueEffects: (mForm: schema_d_exports.FormState | undefined, config: schema_d_exports.FormConfig, values: schema_d_exports.FormValue) => void;
+//#endregion
+//#region temp/packages/form/src/utils/fieldInnerConfig.d.ts
+/** innerConfig 回调的入参：字段自身的配置、所在层级的 model、完整字段路径与表单状态 */
+interface FieldInnerConfigContext {
+  /** 字段自身的配置（已经过 filterFunction 之外的原样配置） */
+  config: schema_d_exports.FormItemConfig;
+  /** 字段所在层级的 model 切片 */
+  model: schema_d_exports.FormValue;
+  /** 字段的完整 prop 路径（含父级前缀），即字段组件拿到的 `props.prop` */
+  prop: string;
+  /** 字段所在层级的 prop 基准（父级 Container 的 `props.prop`），即 `prop` 去掉自身 name 的部分 */
+  parentProp: string;
+  /** 表单状态 */
+  mForm: schema_d_exports.FormState | undefined;
+}
+/** innerConfig 回调的返回值：需要继续遍历的内部配置及其 model / prop 基准 */
+interface FieldInnerConfigResult {
+  /** 内部配置（对应字段组件内部渲染的 `MContainer` 的 `config`） */
+  config: schema_d_exports.FormItemConfig | schema_d_exports.FormItemConfig[];
+  /**
+   * 内部配置对应的 model 切片，默认沿用字段所在层级的 `model`。
+   *
+   * 例如 `code-select` 内部是 `:model="model[name]"`，就应返回 `model[config.name]`。
+   */
+  model?: schema_d_exports.FormValue;
+  /**
+   * 内部配置对应的 prop 基准，默认沿用字段自身的 `prop`。
+   *
+   * 返回的 config 的 `name` 会被追加到这个基准上。所以当内部配置复用了字段自身的 `name`
+   * （如 `display-conds` 内部的 group-list 就叫 `props.name`）时，要返回 `parentProp`，
+   * 否则 name 会被拼两次。
+   */
+  prop?: string;
+}
+/**
+ * 复合字段的内部配置回调。
+ *
+ * 有一类字段组件会在自身内部再渲染 `MContainer` 并传入组件内部临时算出来的 config
+ * （如编辑器的 `code-select` / `event-select` / `style-setter`），这些内部字段同样会向
+ * 父级表单注册 FormItem、参与父表单校验。无渲染校验（`validateValues`）只遍历调用方
+ * 传入的 config 树，看不到这些运行期才产生的配置，因此需要字段作者通过
+ * `registerField(type, { innerConfig })` 把内部配置交出来。
+ *
+ * 返回 `null` / `undefined` 表示该字段本次没有内部配置（例如某些分支下不渲染子表单）。
+ *
+ * 既未登记 innerConfig、也不在叶子字段表里的 type：配置里有 `items` 会下钻子项，
+ * 自身有 `rules` 会校验自身。
+ */
+type FieldInnerConfig = (_ctx: FieldInnerConfigContext) => FieldInnerConfigResult | null | undefined | void;
+//#endregion
+//#region temp/packages/form/src/utils/fieldValueEffects.d.ts
+/** effect 的入参：字段自身的配置、所在层级的 model、完整字段路径、表单值根对象与表单状态 */
+interface FieldMountValueEffectContext {
+  /** 字段自身的配置 */
+  config: schema_d_exports.FormItemConfig;
+  /** 字段所在层级的 model 切片 */
+  model: schema_d_exports.FormValue;
+  /** 字段的完整 prop 路径（含父级前缀），对应 Container 的 `itemProp` */
+  prop: string;
+  /**
+   * 本次处理的表单值根对象，`prop` 即以它为根。
+   *
+   * 需要按路径跨层级写值时用它，不要用 `mForm.values`：对比模式下处理的是 lastValues 那一份，
+   * tab / table 新增行处理的则是还没挂到表单上的一行值，两者都与 `mForm.values` 不是同一个对象。
+   */
+  values: schema_d_exports.FormValue;
+  /** 表单状态 */
+  mForm: schema_d_exports.FormState | undefined;
+}
+/**
+ * 字段对表单值的初始化写入（如 `display` 的 `initValue`、`date` 的格式归一化）。
+ *
+ * 由 `applyMountValueEffects` 在表单值初始化完成后统一执行一次，渲染与无渲染共用。
+ * 因为可能对同一份值重复执行（如 `initValues` 变化后重新初始化），实现必须幂等。
+ */
+type FieldMountValueEffect = (_ctx: FieldMountValueEffectContext) => void;
+/**
+ * 是否为叶子字段 type（内置 ∪ 已登记）。
+ *
+ * @param type - 字段 type
+ * @returns 是否为叶子
+ */
+export declare const isLeafFieldType: (type: string) => boolean;
+//#endregion
+//#region temp/packages/form/src/utils/typeMatch.d.ts
+interface TypeMatchValidateContext {
+  fieldType: string;
+  mForm: schema_d_exports.FormState | undefined;
+  props: any;
+  message?: string;
+}
+/**
+ * 自定义 type 校验器：返回错误文案；通过则返回 undefined。
+ *
+ * 支持返回 Promise，用于需要异步确认取值是否合法的场景（如请求接口校验 id 是否存在）。
+ */
+type TypeMatchValidator = (value: any, context: TypeMatchValidateContext) => string | undefined | Promise<string | undefined>;
+/** 获取某个字段 type 的 typeMatch 校验规则（业务侧优先于内置） */
+export declare const getTypeMatchRule: (type: string) => TypeMatchValidator | undefined;
+/** 删除业务侧 typeMatch 校验规则（不影响内置） */
+export declare const deleteTypeMatchRule: (type: string) => boolean;
+/** 清空业务侧 typeMatch 校验规则（不影响内置） */
+export declare const clearTypeMatchRules: () => void;
+/**
+ * 将值格式化为可读的参考示例字符串。
+ */
+export declare const stringifyExampleValue: (value: any) => string;
+/** 参考建议中可选值全量展示上限；超出时仅举例 EXAMPLE_SUGGESTION_COUNT 个并标明总数。 */
+export declare const MAX_SUGGESTION_OPTIONS = 20;
+/**
+ * 生成可选项参考建议；无可选值时返回空字符串（不追加建议）。
+ * 未超过 MAX_SUGGESTION_OPTIONS 时全部列举；超过时仅举例前 EXAMPLE_SUGGESTION_COUNT 个并标明总数，避免 AI 误以为仅有举例值合法。
+ */
+export declare const optionSuggestion: (optionValues: any[]) => string;
+/**
+ * 校验取值与字段 type 是否匹配；通过返回 undefined，否则返回错误文案。
+ *
+ * 命中的自定义规则是异步校验器时返回 Promise，内置规则始终同步返回。
+ */
+export declare const validateTypeMatch: (value: any, mForm: schema_d_exports.FormState | undefined, props: any, message?: string) => string | undefined | Promise<string | undefined>;
+//#endregion
+//#region temp/packages/form/src/utils/registerField.d.ts
+/**
+ * 自定义字段 type 的登记项。
+ *
+ * 不传或只传空对象：当作叶子，不再下钻 `items`。
+ */
+interface FieldOptions {
+  /**
+   * 渲染用的 Vue 组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-fields-*')`。
+   */
+  component?: Component;
+  /**
+   * 容器组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-form-*')`。
+   */
+  container?: Component;
+  /** 字段挂载时改写 model 的副作用。可与 `innerConfig` 同时登记。 */
+  effect?: FieldMountValueEffect;
+  /**
+   * 按容器模板遍历（tab / table 等）。
+   * 与 `innerConfig` / `effect` 同时传入时 `walk` 优先。
+   */
+  walk?: ContainerWalker;
+  /**
+   * 把内部会挂到父表单的配置交出来。
+   * 可与 `effect` 同时传入：`effect` 负责本字段的值初始化，`innerConfig` 只做配置派生。
+   */
+  innerConfig?: FieldInnerConfig;
+  /** 该 type 的 typeMatch 校验；可与叶子、walk 或 innerConfig 同时登记。 */
+  typeMatch?: TypeMatchValidator;
+}
+/**
+ * 无渲染校验用的登记项，不含 Vue 组件。
+ *
+ * 给 Node / `validateForm` / `submitForm` 用。
+ */
+type HeadlessFieldOptions = Omit<FieldOptions, 'component' | 'container'>;
+/**
+ * 把多份字段登记表按 type 浅合并。后一份只覆盖自己带了的 key，未出现的 key 保留前一份。
+ *
+ * 安装插件时用：Node 侧只登记 `headless`，浏览器再补 `component` / `container`。
+ *
+ * @param tables - 待合并的登记表，`undefined` 会被跳过
+ * @returns 合并后的登记表
+ */
+export declare const mergeFieldOptions: (...tables: Array<Record<string, HeadlessFieldOptions | FieldOptions> | undefined>) => Record<string, FieldOptions>;
+/**
+ * 按字段 type 取已登记的渲染组件（`codeSelect` 与 `code-select` 等价）。
+ *
+ * @param type - 字段 type
+ * @returns 已登记的 Vue 组件；未登记则为 `undefined`
+ */
+declare const getField: (type: string) => Component | undefined;
+/**
+ * 登记一个字段 type 在无渲染校验里的行为，以及可选的渲染组件。
+ *
+ * `type` 会按 Container 的规则归一化为中划线形式（`codeSelect` 与 `code-select` 等价）。
+ * 对同一 type 重复登记按字段浅合并：后一次只覆盖自己传入的 key，未传入的 key 保留。
+ * 传入 `app` 且带了 `component` / `container` 时，会同步 `app.component('m-fields-*'` / `'m-form-*')`。
+ *
+ * @param type - 字段 type
+ * @param [options] - 登记项；省略或空对象视为叶子
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export declare const registerField: (type: string, options?: FieldOptions, app?: App) => void;
+/**
+ * 批量登记字段。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export declare const registerFields: (fields: Record<string, FieldOptions>, app?: App) => void;
+/**
+ * 登记内置字段（`clearFields` / `unregisterField` 不会清掉）。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export declare const registerBuiltInFields: (fields: Record<string, FieldOptions>, app?: App) => void;
+/**
+ * 删除业务侧对指定 type 的登记（不影响内置；主要用于单测）。
+ *
+ * @param type - 字段 type
+ */
+export declare const unregisterField: (type: string) => void;
+/** 清空业务侧登记（不影响内置；主要用于单测）。 */
+export declare const clearFields: () => void;
+//#endregion
+//#region temp/packages/form/src/utils/builtInFields.d.ts
+/**
+ * 内置字段的无渲染登记表（不含 Vue 组件）。
+ *
+ * 本模块只导出数据，不登记。调用方自行 `registerBuiltInFields(builtInFields)`，
+ * 或 `app.use(MagicForm)`（install 里会登记叠上 Vue 组件后的表）。
+ */
+export declare const builtInFields: Record<string, HeadlessFieldOptions>;
+//#endregion
+//#region temp/packages/form/src/utils/validateValues.d.ts
+/** 构造无渲染 formState 所需的参数（与 MForm 的同名 props 对齐） */
+interface HeadlessFormStateOptions {
+  config: schema_d_exports.FormConfig;
+  initValues?: schema_d_exports.FormValue;
+  parentValues?: schema_d_exports.FormValue;
+  keyProp?: string;
+  popperClass?: string;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: schema_d_exports.FormContext;
+}
+/**
+ * 构造一个不依赖组件实例的 `formState`。
+ *
+ * 字段结构与 `Form.vue` 中 provide 给子树的 `mForm` 保持一致，使配置里的
+ * `display` / `rules.validator` / `filter` 等回调拿到的上下文与渲染式校验相同。
+ *
+ * 差异：没有真实的表单实例，因此 `$emit` 为空实现、`fields` 注册表始终为空
+ * （该注册表在整个仓库中只写不读，不参与校验）。
+ */
+export declare const createHeadlessFormState: (options: HeadlessFormStateOptions) => schema_d_exports.FormState;
+/** `validateValues` 参数 */
+interface ValidateValuesOptions extends HeadlessFormStateOptions {
+  /** 是否开启类型匹配校验 */
+  typeMatchValid?: boolean;
+  /**
+   * 校验失败时错误提示前缀是否使用字段的 text 文案。默认 `true`。
+   */
+  useFieldTextInError?: boolean;
+}
+/** `validateValues` 结果 */
+interface ValidateValuesResult {
+  /** 经 `initValue` 初始化并执行字段值初始化写入后的表单值 */
+  values: schema_d_exports.FormValue;
+  /** 汇总后的错误文案（多条以 `<br>` 拼接），校验通过为空字符串 */
+  error: string;
+  /** 原始错误映射，形如 `{ [prop]: [{ field, message }] }` */
+  invalidFields: Record<string, any>;
+}
+/**
+ * 不挂载任何组件，纯逻辑地对「一份 config + 一份值」执行一次完整校验。
+ *
+ * 流程与渲染式校验一一对应，但不需要 DOM，也不会实例化任何字段组件：
+ *
+ * 1. 构造 headless `formState` 并挂上 `context` 读穿；
+ * 2. `initValue` 初始化表单值（默认值、嵌套结构、`onInitValue` 等）；
+ * 3. `applyMountValueEffects` 执行字段登记的值初始化写入（与渲染式共用同一份登记表）；
+ * 4. 遍历 config 树收集所有带规则的字段（等价于渲染出的 FormItem 集合）；
+ * 5. 逐字段交给 async-validator 执行，汇总错误文案。
+ *
+ * @example
+ * ```ts
+ * const { error, values } = await validateValues({
+ *   config: [...],
+ *   initValues: { name: '' },
+ *   typeMatchValid: true,
+ * });
+ * ```
+ */
+export declare const validateValues: (options: ValidateValuesOptions) => Promise<ValidateValuesResult>;
+//#endregion
+//#region temp/packages/form/src/utils/validateError.d.ts
+/**
+ * 通过 name 从 config 中查找对应的 text
+ *
+ * @param name - 字段名，支持点分隔的路径格式，如 'a.b.c'
+ * @param config - 表单配置数组
+ * @returns 找到的 text 值，如果未找到则返回 undefined
+ */
+export declare const getTextByName: (name: string, config?: schema_d_exports.FormConfig) => string | undefined;
+/**
+ * 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
+ *
+ * `useFieldTextInError` 为 `true`（默认）时用字段的 text 文案作为错误前缀，找不到则回退为字段 name。
+ *
+ * 由渲染式校验（Form.vue 的 `submitForm` / `validate`）与无渲染校验（`validateValues`）共用，
+ * 保证两条校验链路产出的错误文案格式完全一致。
+ *
+ * @param invalidFields - async-validator 产出的字段错误表
+ * @param [options] - 文案选项
+ * @param [options.config] - 用于查找 text 的表单配置
+ * @param [options.useFieldTextInError=true] - 错误前缀是否使用字段 text
+ * @returns 拼接后的错误文案；无错误时为空串
+ */
+export declare const formatValidateError: (invalidFields: Record<string, any>, { config, useFieldTextInError }?: {
+  config?: schema_d_exports.FormConfig;
+  useFieldTextInError?: boolean;
+}) => string;
+//#endregion
+//#region temp/packages/form/src/utils/submitHeadless.d.ts
+/**
+ * submitForm 函数参数（与 Form.vue 组件 props 对齐）
+ */
+interface SubmitFormOptions {
+  /** 表单配置 */
+  config: schema_d_exports.FormConfig;
+  /** 表单初始值 */
+  initValues?: Record<string, any>;
+  /** 需对比的值（开启对比模式时传入） */
+  lastValues?: Record<string, any>;
+  /** 是否开启对比模式 */
+  isCompare?: boolean;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  disabled?: boolean;
+  height?: string;
+  stepActive?: string | number;
+  size?: 'small' | 'default' | 'large';
+  inline?: boolean;
+  labelPosition?: 'top' | 'left' | 'right';
+  keyProp?: string;
+  popperClass?: string;
+  preventSubmitDefault?: boolean;
+  /**
+   * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: schema_d_exports.FormContext;
+  /** 透传给 Form.submitForm 的参数：是否直接返回原始响应式 values */
+  native?: boolean;
+  /**
+   * 是否在 resolve 结果中携带 changeRecords（变更记录）。
+   * 开启后 resolve 的结果为 `{ values, changeRecords }`，否则仅 resolve values。
+   */
+  returnChangeRecords?: boolean;
+  /**
+   * 父级应用上下文，用于继承全局组件、指令、provide 等。
+   * 仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+/**
+ * 开启 `returnChangeRecords` 时 submitForm 的返回结果
+ */
+interface SubmitFormResult {
+  /** 校验通过后的表单值 */
+  values: any;
+  /** 表单变更记录 */
+  changeRecords: ChangeRecord[];
+}
+/**
+ * validateForm 函数参数（与 Form.vue 组件 props 对齐，取校验所需子集）
+ */
+interface ValidateFormOptions {
+  /** 表单配置 */
+  config: schema_d_exports.FormConfig;
+  /** 待校验的表单值 */
+  initValues?: Record<string, any>;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  keyProp?: string;
+  /**
+   * 校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: schema_d_exports.FormContext;
+  /**
+   * 父级应用上下文。仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次校验并取回表单值（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export declare const submitForm: (options: SubmitFormOptions) => Promise<any>;
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次静默校验（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export declare const validateForm: (options: ValidateFormOptions) => Promise<string>;
+declare namespace headless_d_exports {
+  export { ChangeRecord, CollectedField, ContainerChangeEventData, FORM_CONTEXT_KEY, FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY, FieldInnerConfig, FieldInnerConfigContext, FieldInnerConfigError, FieldInnerConfigResult, FieldMountValueEffect, FieldMountValueEffectContext, FieldOptions, FormDiffConfig, FormLabelSlotProps, FormSlots, HeadlessFieldOptions, HeadlessFormStateOptions, MAX_SUGGESTION_OPTIONS, SubmitFormOptions, SubmitFormResult, TypeMatchValidateContext, TypeMatchValidator, ValidateError, ValidateFormOptions, ValidateValuesOptions, ValidateValuesResult, adaptFormValidator, appendProp, applyMountValueEffects, builtInFields, clearFields, clearTypeMatchRules, collectValidatableFields, createFormStateBase, createFormStateProxy, createHeadlessFormState, createObjectProp, createValues, datetimeFormatter, deleteTypeMatchRule, display, filterFunction, formatValidateError, getDataByPage, getField as getFormField, getItemProp, getNativeRules, getRules, getTextByName, getTypeMatchRule, initValue, isFieldInnerConfigError, isLeafFieldType, isValidName, mergeFieldOptions, mergeFormContexts, optionSuggestion, registerBuiltInFields, registerField, registerFields, resolveItemType, sortArray, sortChange, stringifyExampleValue, submitForm, unregisterField, validateForm, validateTypeMatch, validateValues };
+}
+//#endregion
+export { type CollectedField, type FieldInnerConfig, type FieldInnerConfigContext, type FieldInnerConfigResult, type FieldMountValueEffect, type FieldMountValueEffectContext, type FieldOptions, type HeadlessFieldOptions, type HeadlessFormStateOptions, type SubmitFormOptions, type SubmitFormResult, type TypeMatchValidateContext, type TypeMatchValidator, type ValidateFormOptions, type ValidateValuesOptions, type ValidateValuesResult, getField as getFormField };