/*
 * Tencent is pleased to support the open source community by making TMagicEditor available.
 *
 * Copyright (C) 2025 Tencent.  All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import {
  type AppContext,
  type Component,
  createApp,
  defineComponent,
  h,
  nextTick,
  provide,
  type Ref,
  ref,
  watch,
} from 'vue';

import { applyExtendState } from './utils/form';
import Form from './Form.vue';
import { type ChangeRecord, FORM_SILENT_MODE_KEY, type FormConfig, type FormState } from './schema';

// #region SubmitFormOptions
/**
 * submitForm 函数参数（与 Form.vue 组件 props 对齐）
 */
export interface SubmitFormOptions {
  /** 表单配置 */
  config: 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?: string;
  keyProp?: string;
  popperClass?: string;
  preventSubmitDefault?: boolean;
  /**
   * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
   * 默认 `true`，置为 `false` 时直接使用字段 name。
   */
  useFieldTextInError?: boolean;
  extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
  /** 透传给 Form.submitForm 的参数：是否直接返回原始响应式 values */
  native?: boolean;
  /**
   * 是否在 resolve 结果中携带 changeRecords（变更记录）。
   * 开启后 resolve 的结果为 `{ values, changeRecords }`，否则仅 resolve values。
   */
  returnChangeRecords?: boolean;
  /**
   * 父级应用上下文，用于继承全局组件、指令、provide 等。
   * 通常通过 `app._context` 或 `getCurrentInstance()?.appContext` 获取。
   */
  appContext?: AppContext | null;
  /** 等待表单初始化的最长时间（毫秒），超时将以错误 reject。默认 10000ms */
  timeout?: number;
  /**
   * 调试模式。默认 `false`。
   *
   * - `false`：表单以隐藏方式挂载，初始化完成后自动提交（原有行为）。
   * - `true`：将表单以弹层形式可见地渲染在页面上，需手动点击「确定」才会触发校验/提交，
   *   点击「取消」则以 reject 中断；校验失败时保留弹层并展示错误信息，便于修正后重试。
   *   调试模式下 `timeout` 不生效（等待人工操作）。
   */
  debug?: boolean;
  typeMatchValid?: boolean;
  /**
   * 外部中断信号。abort 时会立即以 `signal.reason` reject 并卸载临时表单实例、移除容器。
   * 主要用于 `debug` 模式（无超时兜底）下取消一个被放弃的表单弹层，避免其无限驻留在页面上。
   */
  signal?: AbortSignal;
}
// #endregion SubmitFormOptions

// #region SubmitFormResult
/**
 * 开启 `returnChangeNodes` 时 submitForm 的返回结果
 */
export interface SubmitFormResult {
  /** 校验通过后的表单值 */
  values: any;
  /** 表单变更记录 */
  changeRecords: ChangeRecord[];
}
// #endregion SubmitFormResult

// #region mountFormInstance
/**
 * 构造 wrapper 组件的工厂：在合适时机调用 MForm 实例方法并 resolve/reject、清理实例。
 *
 * 由调用方决定「等待 `initialized` 后自动执行」还是「等待人工触发」（debug 模式），
 * 以及「调用 `submitForm` 还是 `validate`」「结果如何包装」，从而复用公共脚手架。
 */
type FormWrapperFactory<T> = (ctx: {
  /** 透传给 Form 组件的 props（由工厂统一注入，避免调用方重复闭包） */
  formProps: Record<string, any>;
  /** 指向挂载的 MForm 实例 */
  formRef: Ref<any>;
  /** 卸载实例并移除容器，resolve/reject 后必须调用以避免泄漏 */
  cleanup: () => void;
  /** resolve 外层 Promise */
  resolve: (value: T | PromiseLike<T>) => void;
  /** reject 外层 Promise */
  reject: (reason?: any) => void;
}) => Component;

interface MountFormInstanceOptions<T> {
  /** 透传给 Form 组件的 props */
  formProps: Record<string, any>;
  /** 父级应用上下文，用于继承全局组件、指令、provide 等 */
  appContext?: AppContext | null;
  /** 等待表单初始化的最长时间（毫秒），<=0 时回退到默认超时以保证兜底清理生效 */
  timeout: number;
  /** 超时 reject 的错误文案 */
  timeoutMessage: string;
  /** 是否以 `display:none` 隐藏容器。调试模式需可见，应传 `false` */
  hidden?: boolean;
  /** 是否跳过超时注册。调试模式等待人工操作，应传 `true` */
  skipTimeout?: boolean;
  /** 外部中断信号：abort 时会 reject 并卸载实例、移除容器，用于取消无超时（如 debug）的挂载 */
  signal?: AbortSignal;
  /** 构造 wrapper 组件 */
  createWrapper: FormWrapperFactory<T>;
}

/** 未指定或传入非正数 timeout 时的兜底超时（毫秒），保证非 debug 挂载始终能被清理 */
const DEFAULT_MOUNT_TIMEOUT = 10000;

/**
 * submitForm / validateForm 的公共脚手架：
 *
 * 创建临时容器 → 挂载一个 wrapper 组件（内含 MForm）→ 提供统一的 cleanup / timeout / appContext 继承 →
 * 由 `createWrapper` 决定「何时调用 MForm 的哪个方法、如何 resolve/reject」。
 *
 * 调用方只需关注差异逻辑（调用 `submitForm` 还是 `validate`、结果如何包装、是否需要调试弹层），
 * 容器创建、卸载、超时、上下文注入等模板代码在此统一收口。
 */
const mountFormInstance = <T>(options: MountFormInstanceOptions<T>): Promise<T> => {
  const {
    formProps,
    appContext,
    timeout,
    timeoutMessage,
    hidden = true,
    skipTimeout = false,
    signal,
    createWrapper,
  } = options;

  return new Promise<T>((resolve, reject) => {
    // 已中断则直接 reject，不创建任何容器/实例
    if (signal?.aborted) {
      reject(signal.reason ?? new Error('mountFormInstance aborted'));
      return;
    }

    let cleaned = false;
    let timer: ReturnType<typeof setTimeout> | null = null;
    let onAbort: (() => void) | null = null;
    // 用 holder 持有 app，使 cleanup 可在 app 创建之前定义（const app + 无 TDZ / 无 use-before-define）
    const instance: { app: ReturnType<typeof createApp> | null } = { app: null };

    const container = document.createElement('div');
    if (hidden) {
      container.style.display = 'none';
    }
    document.body.appendChild(container);

    const cleanup = () => {
      if (cleaned) return;
      cleaned = true;
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      if (signal && onAbort) {
        signal.removeEventListener('abort', onAbort);
        onAbort = null;
      }
      try {
        instance.app?.unmount();
      } catch {
        // ignore
      }
      container.parentNode?.removeChild(container);
    };

    // 支持外部通过 AbortSignal 主动中断：debug 模式无超时兜底，若调用方放弃了该 Promise，
    // 可通过 abort 卸载实例、移除遮罩/容器，避免无限驻留在 DOM 中。
    if (signal) {
      onAbort = () => {
        if (cleaned) return;
        reject(signal.reason ?? new Error('mountFormInstance aborted'));
        cleanup();
      };
      signal.addEventListener('abort', onAbort);
    }

    // 从容器创建到 mount 的全流程统一 try/catch：任一步骤（createWrapper/createApp/上下文合并/mount）
    // 抛错都会走到 cleanup，避免已插入 body 的 container 及未挂载的 app 残留导致泄漏。
    try {
      const formRef = ref<any>(null);

      // 将 extendState 从 formProps 中剥离：不由 Form.vue 的 async watchEffect 异步应用，
      // 而是在 wrapper 中通过 sync watch 在 formRef 就绪后直接写入 formState，
      // 避免 display 等 filterFunction 在首次渲染时读到 undefined。
      // 与 CompareForm / FormPanel 中「formRef.value.formState.services = ...」的做法一致。
      const { extendState, ...restFormProps } = formProps;

      const userWrapper = createWrapper({ formRef, formProps: restFormProps, cleanup, resolve, reject });

      const wrapperComponent =
        typeof extendState === 'function'
          ? defineComponent({
              name: 'MFormExtendStateInjector',
              setup() {
                watch(
                  () => formRef.value,
                  (form) => {
                    if (!form) return;
                    let result: any;
                    try {
                      result = extendState(form.formState);
                    } catch (e) {
                      console.error('[MForm] extendState failed:', e);
                      return;
                    }
                    // formState 的内置 key 快照：在 extendState 合并前捕获，
                    // 供 applyExtendState 禁止 extendState 覆盖这些已有字段（只能新增），
                    // 与 Form.vue 中 reservedStateKeys 的语义保持一致。
                    const reservedStateKeys = new Set<string | symbol>(Reflect.ownKeys(form.formState));
                    // 合并逻辑收口在 applyExtendState：props 派生的只读 getter 字段
                    // （keyProp 等）以普通字段形式返回时会被跳过并告警，避免 proxy set 抛错
                    const apply = (state: Record<string, any> | null | undefined) =>
                      applyExtendState(form.formState, state, reservedStateKeys);
                    if (result && typeof result.then === 'function') {
                      result.then(apply, (e: any) => console.error('[MForm] extendState failed:', e));
                    } else {
                      apply(result);
                    }
                  },
                  { flush: 'sync', immediate: true },
                );
                return () => h(userWrapper);
              },
            })
          : userWrapper;

      // 静默（隐藏挂载）模式下注入静默标记：vs-code 等重型字段组件可据此跳过自身渲染，
      // 校验/取值依赖 FormItem 与 model 值，与叶子 UI 组件无关（见 FORM_SILENT_MODE_KEY 注释）。
      // 用组件级 provide 而非 app.provide：appContext 合并后 app._context.provides 与父级应用
      // 共享引用，app.provide 会把标记泄漏到父级应用。
      const rootComponent = hidden
        ? defineComponent({
            name: 'MFormSilentProvider',
            setup() {
              provide(FORM_SILENT_MODE_KEY, true);
              return () => h(wrapperComponent);
            },
          })
        : wrapperComponent;

      const app = createApp(rootComponent);
      instance.app = app;

      // 继承父级应用上下文（components / directives / provides / config 等）
      if (appContext) {
        Object.assign(app._context, appContext);
      }

      // 非 debug（未跳过超时）场景始终注册超时兜底：timeout 为非正数时回退到默认值，
      // 避免表单永不初始化时实例/容器/watcher 无限驻留而泄漏。
      if (!skipTimeout) {
        const effectiveTimeout = timeout > 0 ? timeout : DEFAULT_MOUNT_TIMEOUT;
        timer = setTimeout(() => {
          if (!cleaned) {
            reject(new Error(timeoutMessage));
            cleanup();
          }
        }, effectiveTimeout);
      }

      app.mount(container);
    } catch (err) {
      reject(err);
      cleanup();
    }
  });
};
// #endregion mountFormInstance

// #region createDebugWrapper
interface DebugWrapperOptions {
  /** 指向挂载的 MForm 实例 */
  formRef: Ref<any>;
  /** 透传给 Form 组件的 props */
  formProps: Record<string, any>;
  /** 弹层标题 */
  title: string;
  /** wrapper 组件名 */
  name: string;
  /**
   * 点击「确定」触发；接收 `setError`，校验失败时可调用以在弹层展示错误并保留弹层供修正后重试，
   * 校验通过则由调用方自行 resolve + cleanup。
   */
  onConfirm: (setError: (msg: string) => void) => void | Promise<void>;
  /** 点击「取消」触发（通常 reject + cleanup） */
  onCancel: () => void;
}

/**
 * 构造调试模式下的可见弹层 wrapper：以 fixed 遮罩居中渲染 MForm，提供「确定 / 取消」按钮与错误展示区。
 *
 * submitForm 与 validateForm 的调试弹层 UI 完全一致，仅「确定」时调用的实例方法、错误处理与取消文案不同，
 * 这些差异通过 `onConfirm` / `onCancel` 注入，弹层结构在此统一收口。
 */
const createDebugWrapper = (options: DebugWrapperOptions): Component => {
  const { formRef, formProps, title, name, onConfirm, onCancel } = options;

  const btnBase = {
    padding: '8px 20px',
    fontSize: '14px',
    lineHeight: '1',
    border: '1px solid #dcdfe6',
    borderRadius: '4px',
    cursor: 'pointer',
  };

  return defineComponent({
    name,
    setup() {
      // 校验失败信息展示区
      const errorMsg = ref('');
      const setError = (msg: string) => {
        errorMsg.value = msg;
      };

      return () =>
        h(
          'div',
          {
            style: {
              position: 'fixed',
              inset: '0',
              zIndex: '10000',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              background: 'rgba(0, 0, 0, 0.5)',
            },
          },
          [
            h(
              'div',
              {
                style: {
                  display: 'flex',
                  flexDirection: 'column',
                  width: '600px',
                  maxWidth: '90vw',
                  maxHeight: '85vh',
                  background: '#fff',
                  borderRadius: '8px',
                  boxShadow: '0 8px 24px rgba(0, 0, 0, 0.2)',
                  overflow: 'hidden',
                },
              },
              [
                h(
                  'div',
                  {
                    style: {
                      padding: '16px 20px',
                      fontSize: '16px',
                      fontWeight: '600',
                      borderBottom: '1px solid #ebeef5',
                    },
                  },
                  title,
                ),
                h(
                  'div',
                  {
                    style: {
                      flex: '1',
                      padding: '20px',
                      overflow: 'auto',
                    },
                  },
                  [
                    h(Form as Component, { ...formProps, ref: formRef }),
                    errorMsg.value
                      ? h('div', {
                          style: {
                            marginTop: '12px',
                            color: '#f56c6c',
                            fontSize: '13px',
                            lineHeight: '1.5',
                          },
                          innerHTML: errorMsg.value,
                        })
                      : null,
                  ],
                ),
                h(
                  'div',
                  {
                    style: {
                      display: 'flex',
                      justifyContent: 'flex-end',
                      gap: '12px',
                      padding: '12px 20px',
                      borderTop: '1px solid #ebeef5',
                    },
                  },
                  [
                    h('button', { type: 'button', onClick: onCancel, style: { ...btnBase } }, '取消'),
                    h(
                      'button',
                      {
                        type: 'button',
                        onClick: () => onConfirm(setError),
                        style: {
                          ...btnBase,
                          color: '#fff',
                          background: '#409eff',
                          borderColor: '#409eff',
                        },
                      },
                      '确定',
                    ),
                  ],
                ),
              ],
            ),
          ],
        );
    },
  });
};
// #endregion createDebugWrapper

/**
 * 以命令式方式调用 Form.vue 完成一次表单校验/提交。
 *
 * 类似 ElMessage 的用法：传入 props（包含 `config`/`initValues` 等），函数内部会临时挂载
 * 一个不可见的 Form 组件实例，等待初始化完成后调用其 `submitForm` 方法，
 * 校验通过则 resolve 表单值，校验失败则 reject 错误信息，最后自动卸载实例。
 *
 * @example
 * ```ts
 * import { submitForm } from '@tmagic/form';
 *
 * try {
 *   const values = await submitForm({
 *     config: [...],
 *     initValues: { name: 'foo' },
 *   });
 *   console.log(values);
 * } catch (e) {
 *   console.error(e);
 * }
 *
 * // 需要同时获取变更记录时：
 * const { values, changeRecords } = await submitForm({
 *   config: [...],
 *   initValues: { name: 'foo' },
 *   returnChangeRecords: true,
 * });
 *
 * // 调试模式：可见地渲染表单，点击「确定」才提交：
 * const values = await submitForm({
 *   config: [...],
 *   initValues: { name: 'foo' },
 *   debug: true,
 * });
 * ```
 */
export const submitForm = (options: SubmitFormOptions): Promise<any> => {
  const { native, appContext, timeout = 10000, returnChangeRecords, debug = false, signal, ...formProps } = options;

  return mountFormInstance<any>({
    formProps,
    appContext,
    timeout,
    signal,
    // 调试模式需把表单展示出来；普通模式隐藏挂载
    hidden: !debug,
    // 调试模式等待人工操作，不应用超时
    skipTimeout: debug,
    timeoutMessage: `submitForm timeout after ${timeout}ms: form is not initialized.`,
    createWrapper: ({ formRef, formProps, cleanup, resolve, reject }) => {
      /**
       * 执行一次提交：nextTick 等待子组件渲染 → 快照 changeRecords → 调用实例 submitForm → resolve。
       * 校验失败时交给 `onValidateError` 决定「保留弹层展示错误（debug）」还是「reject 并清理（普通）」，
       * 从而让 debug 与普通模式共享同一份提交逻辑。
       */
      const doSubmit = async (onValidateError: (err: any) => void) => {
        try {
          // 等待子组件（FormItem 等）完成首次渲染，确保 validate 能拿到所有字段
          await nextTick();
          // submitForm 校验通过后会清空 changeRecords，需在调用前先做快照
          const changeRecords: ChangeRecord[] = [...(formRef.value?.changeRecords ?? [])];
          const result = await formRef.value.submitForm(native);
          resolve(returnChangeRecords ? { values: result, changeRecords } : result);
          cleanup();
        } catch (err) {
          onValidateError(err);
        }
      };

      // 调试模式：可见地渲染表单，点击「确定」才提交，点击「取消」则中断
      if (debug) {
        return createDebugWrapper({
          formRef,
          formProps,
          name: 'MFormSubmitWrapper',
          title: 'submitForm 调试',
          onConfirm: (setError) =>
            doSubmit((err) => {
              // 校验失败时保留弹层并展示错误，便于修正后重新提交
              setError(err instanceof Error ? err.message : String(err));
            }),
          onCancel: () => {
            reject(new Error('submitForm canceled in debug mode.'));
            cleanup();
          },
        });
      }

      // 普通模式：表单初始化完成后自动提交
      return defineComponent({
        name: 'MFormSubmitWrapper',
        setup() {
          const stop = watch(
            () => formRef.value?.initialized,
            (initialized) => {
              if (!initialized) return;
              stop();
              doSubmit((err) => {
                reject(err);
                cleanup();
              });
            },
            { flush: 'post', immediate: true },
          );

          return () => h(Form as Component, { ...formProps, ref: formRef });
        },
      });
    },
  });
};

// #region ValidateFormOptions
/**
 * validateForm 函数参数（与 Form.vue 组件 props 对齐，取校验所需子集）
 */
export interface ValidateFormOptions {
  /** 表单配置 */
  config: FormConfig;
  /** 待校验的表单值 */
  initValues?: Record<string, any>;
  parentValues?: Record<string, any>;
  labelWidth?: string;
  keyProp?: string;
  /**
   * 校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
   * 默认 `true`，置为 `false` 时直接使用字段 name。
   */
  useFieldTextInError?: boolean;
  extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
  /**
   * 父级应用上下文，用于继承全局组件、指令、provide 等。
   * 通常通过 `app._context` 或 `getCurrentInstance()?.appContext` 获取。
   */
  appContext?: AppContext | null;
  /** 等待表单初始化的最长时间（毫秒），超时将以错误 reject。默认 10000ms */
  timeout?: number;
  /**
   * 调试模式。默认 `false`。
   *
   * - `false`：以隐藏方式挂载，初始化完成后自动校验并 resolve 错误文案（原有静默行为）。
   * - `true`：将表单以弹层形式可见地渲染在页面上，需手动点击「确定」才会触发校验，
   *   点击「取消」则以 reject 中断；校验失败时在弹层内展示错误信息并保留弹层，便于修正后重试，
   *   校验通过则 resolve 空字符串。调试模式下 `timeout` 不生效（等待人工操作）。
   */
  debug?: boolean;
  typeMatchValid?: boolean;
  /**
   * 外部中断信号。abort 时会立即以 `signal.reason` reject 并卸载临时表单实例、移除容器。
   * 主要用于 `debug` 模式（无超时兜底）下取消一个被放弃的表单弹层，避免其无限驻留在页面上。
   */
  signal?: AbortSignal;
}
// #endregion ValidateFormOptions

// #region stripTabLazy
/**
 * 深拷贝配置值，保留函数（display / onTabClick 等回调）引用，避免破坏配置中的回调。
 */
const cloneConfigValue = (value: any): any => {
  if (Array.isArray(value)) {
    return value.map(cloneConfigValue);
  }
  if (value && typeof value === 'object') {
    return Object.keys(value).reduce<Record<string, any>>((acc, key) => {
      acc[key] = cloneConfigValue(value[key]);
      return acc;
    }, {});
  }
  return value;
};

/**
 * 深度遍历配置，去掉所有 type 为 'tab' 的容器中各标签页（items）的 lazy 配置。
 */
const removeTabItemsLazy = (node: any): void => {
  if (Array.isArray(node)) {
    node.forEach(removeTabItemsLazy);
    return;
  }
  if (!node || typeof node !== 'object') return;

  if (node.type === 'tab' && Array.isArray(node.items)) {
    node.items.forEach((pane: any) => {
      if (pane && typeof pane === 'object') {
        delete pane.lazy;
      }
    });
  }

  Object.keys(node).forEach((key) => {
    removeTabItemsLazy(node[key]);
  });
};

/**
 * 返回一份去除了 tab 标签页 lazy 的配置副本。
 *
 * tab 容器开启 lazy 时，非激活标签页的内容不会渲染，导致 validateForm 静默挂载后
 * 无法校验到这些标签页内的字段。校验场景需要一次性渲染全部字段，故在此统一去除 lazy。
 * 处理基于深拷贝，不会污染调用方传入的原始 config。
 */
export const stripTabItemsLazy = (config: FormConfig): FormConfig => {
  const cloned = cloneConfigValue(config);
  removeTabItemsLazy(cloned);
  return cloned;
};
// #endregion stripTabLazy

/**
 * 以命令式方式对一份「表单配置 + 值」做一次静默校验，**不依赖也不影响任何已渲染的表单**。
 *
 * 与 `submitForm` 类似，内部会临时挂载一个不可见的 MForm 实例，等待其初始化完成后调用
 * 实例的 `validate` 方法，返回汇总后的错误文案，随后自动卸载实例。
 *
 * 与 `submitForm` 的区别：
 * - 「静默」：校验失败不抛异常、不触发 `error` 事件、不返回表单值；
 * - 仅用于「探测」配置是否合法，适合源码保存后校验、批量校验组件配置等场景。
 *
 * 由于每次都新建一个独立的 MForm 实例，调用方无需持有任何表单 ref，也不会污染
 * 页面上正在展示的表单状态。
 *
 * @returns 校验通过返回空字符串 `''`，否则返回以 `<br>` 拼接的错误文案。
 *   仅在初始化超时或挂载失败等异常情况下才会 reject。
 *
 * @example
 * ```ts
 * import { validateForm } from '@tmagic/form';
 *
 * const error = await validateForm({
 *   config: [...],
 *   initValues: { name: 'foo' },
 *   appContext: getCurrentInstance()?.appContext,
 * });
 * if (error) {
 *   // 配置不合法，error 为错误文案
 * }
 *
 * // 调试模式：可见地渲染表单，点击「确定」才校验，校验失败保留弹层可修正重试：
 * const error = await validateForm({
 *   config: [...],
 *   initValues: { name: 'foo' },
 *   debug: true,
 * });
 * ```
 */
export const validateForm = (options: ValidateFormOptions): Promise<string> => {
  const { appContext, timeout = 10000, debug = false, config, signal, ...rest } = options;

  // 去掉 tab 容器各标签页的 lazy，确保懒加载标签页内的字段也参与校验
  const formProps = { ...rest, config: stripTabItemsLazy(config) };

  return mountFormInstance<string>({
    formProps,
    appContext,
    timeout,
    signal,
    // 调试模式需把表单展示出来；普通模式隐藏挂载
    hidden: !debug,
    // 调试模式等待人工操作，不应用超时
    skipTimeout: debug,
    timeoutMessage: `validateForm timeout after ${timeout}ms: form is not initialized.`,
    createWrapper: ({ formRef, formProps, cleanup, resolve, reject }) => {
      /**
       * 执行一次校验：nextTick 等待子组件渲染 → 调用实例 validate → 通过则 resolve ''。
       * 校验失败（返回非空错误文案）时交给 `onInvalid` 决定「静默 resolve 错误文案（普通）」
       * 还是「在弹层展示错误并保留供重试（debug）」，从而让两种模式共享同一份校验逻辑。
       */
      const doValidate = async (onInvalid: (error: string) => void) => {
        try {
          // 等待子组件（FormItem 等）完成首次渲染，确保 validate 能拿到所有字段
          await nextTick();
          // 复用 Form.vue 实例的静默校验方法：校验通过返回 ''，失败返回错误文案，均不抛异常
          const error = await formRef.value.validate();
          if (error) {
            onInvalid(error);
          } else {
            resolve('');
            cleanup();
          }
        } catch (err) {
          reject(err);
          cleanup();
        }
      };

      // 调试模式：可见地渲染表单，点击「确定」才校验，点击「取消」则中断
      if (debug) {
        return createDebugWrapper({
          formRef,
          formProps,
          name: 'MFormValidateWrapper',
          title: 'validateForm 调试',
          onConfirm: (setError) =>
            doValidate((error) => {
              // 校验失败时保留弹层并展示错误，便于修正后重新校验
              setError(error);
            }),
          onCancel: () => {
            reject(new Error('validateForm canceled in debug mode.'));
            cleanup();
          },
        });
      }

      // 普通模式：表单初始化完成后自动校验（静默 resolve 错误文案）
      return defineComponent({
        name: 'MFormValidateWrapper',
        setup() {
          const stop = watch(
            () => formRef.value?.initialized,
            (initialized) => {
              if (!initialized) return;
              stop();
              doValidate((error) => {
                // 静默：校验失败也以错误文案 resolve（不抛异常）
                resolve(error);
                cleanup();
              });
            },
            { flush: 'post', immediate: true },
          );

          return () => h(Form as Component, { ...formProps, ref: formRef });
        },
      });
    },
  });
};