@xbeeant/form-engine-react 0.0.2 → 0.0.4

package/src/components/{NexusField.tsx → nexus-field.tsx}

@@ -1,10 +1,10 @@
-import type { CSSProperties, FocusEvent } from 'react';
+import type { CSSProperties, FocusEvent, ReactElement } from 'react';
 import { useCallback, useContext, useMemo, useSyncExternalStore } from 'react';
-import { FieldInheritContext } from '../contexts/FieldInheritContext';
-import { GridContext } from '../contexts/GridContext';
-import { LayoutConfigContext } from '../contexts/LayoutConfigContext';
-import { useNexusContext } from '../contexts/NexusContext';
-import { resolveColSpan } from '../utils/resolveColSpan';
+import { FieldInheritContext } from '../contexts/field-inherit-context';
+import { GridContext } from '../contexts/grid-context';
+import { LayoutConfigContext } from '../contexts/layout-config-context';
+import { useNexusContext } from '../contexts/nexus-context';
+import { resolveColSpan } from '../utils/resolve-col-span';
 
 interface NexusFieldProps {
   dataPath: string;
@@ -82,6 +82,49 @@ export function NexusField({ dataPath, layoutKey }: NexusFieldProps) {
     return values;
   }, [state?.reactions, engine]);
 
+  // x-render addons — 为 widget 组件提供统一的表单数据访问、校验、Schema 操作入口
+  // 对齐 x-render 自定义组件的 addons API
+  const addons = useMemo(() => {
+    const arrayPath = state?.meta.itemOf;
+    const isItemField = !!arrayPath;
+    const indexMatch = isItemField ? dataPath.match(/\[(\d+)\]/) : undefined;
+    const index = indexMatch ? Number(indexMatch[1]) : undefined;
+
+    return {
+      get formData() {
+        return form.getValues();
+      },
+      get rootValue() {
+        return form.getValues();
+      },
+      value: state?.value,
+      dataPath,
+      path: dataPath,
+      index,
+      parentValues: arrayPath ? form.getValueByPath(arrayPath) : undefined,
+      getValue: (p: string) => form.getValueByPath(p),
+      setValue: (p: string, v: unknown) => form.setValueByPath(p, v),
+      onItemChange: (p: string, v: unknown) => form.setValueByPath(p, v),
+      validate: async (p?: string) => {
+        if (p) {
+          await form.validateFields([p]);
+        } else {
+          await form.validateFields([dataPath]);
+        }
+      },
+      validateFields: async (paths?: string[]) => {
+        await form.validateFields(paths);
+      },
+      submit: () => form.submit(),
+      resetFields: () => form.resetFields(),
+      setSchema: (s: Record<string, unknown>) =>
+        form.setSchema(s as any),
+      setSchemaByPath: (p: string, patch: Record<string, unknown>) =>
+        form.setSchemaByPath(p, patch),
+      getSchema: () => form.getSchema(),
+    };
+  }, [form, dataPath, state?.value, state?.meta.itemOf]);
+
   if (!state) {
     // 仅当引擎已初始化（version > 0）但字段仍未找到时才发出警告
     // 初始化过程中的短暂空状态不应报警
@@ -146,37 +189,71 @@ export function NexusField({ dataPath, layoutKey }: NexusFieldProps) {
     ...(effectiveColSpan ? { gridColumn: `span ${effectiveColSpan}` } : {}),
   };
 
+  // 默认包裹：所有 widget 统一由 FieldWrapper 包裹（引擎注册，UI 层提供），
+  // 仅当 label === false（字段级或表单级）时 FieldWrapper 不包裹 Form.Item。
+  // 未注册 FieldWrapper（纯 react 无 ui 层）时直接渲染裸 widget。
+  const FieldWrapper = engine.getFieldWrapper();
+
+  // Form.Item 消费的元数据 props 剥离给 FieldWrapper，避免透传到底层 antd 控件：
+  // - required: 会让 <input required> 触发浏览器原生校验
+  // - errors/title/description/label/extra/width/displayType/labelWidth/column:
+  //   作为未知属性透传到 DOM 会产生 React 警告
+  // width / colSpan / displayType / labelWidth / column 是布局属性，
+  // 由 NexusField 外层 <div> 的 wrapperStyle 统一消费，不透传给 FieldWrapper（Form.Item），
+  // 避免外层 div 与 Form.Item 重复设置 width。
+  const fieldWrapperProps = {
+    label: state.meta.label,
+    title: state.meta.title,
+    description: state.meta.description,
+    tooltip: state.meta.tooltip,
+    errors: state.errors,
+    required: state.required,
+    extra: state.meta.extra,
+    displayType: fieldDisplayType,
+    labelWidth: fieldLabelWidth,
+    column: fieldColumn,
+  };
+
+  // widget 仅接收控件相关 props（value/onChange/状态/选项/表单引用/自有 props）
+  const widgetProps = {
+    dataPath,
+    path: dataPath,
+    value: state.value,
+    onChange: handleChange,
+    disabled,
+    readOnly,
+    loading: state.loading,
+    placeholder: state.meta.placeholder,
+    options,
+    form,
+    addons,
+    dependValues,
+    items: state.meta.items,
+    schema: state.meta.schema,
+    // 远程选项数据版本：reloadRemoteData 后变化，widget 据此跳过缓存重新请求
+    remoteVersion: engine.getRemoteDataVersion(dataPath),
+    ...state.props,
+  };
+
+  let control: ReactElement;
+  if (FieldWrapper) {
+    control = (
+      <FieldWrapper key={layoutKey} {...fieldWrapperProps}>
+        <Widget {...widgetProps} />
+      </FieldWrapper>
+    );
+  } else {
+    control = <Widget key={layoutKey} {...widgetProps} />;
+  }
+
   return (
     <div
       data-nexus-field={dataPath}
+      className={readOnly ? 'nexus-field-readonly' : undefined}
       onBlur={handleBlur}
       style={Object.keys(wrapperStyle).length > 0 ? wrapperStyle : undefined}
     >
-      <Widget
-        key={layoutKey}
-        dataPath={dataPath}
-        path={dataPath}
-        value={state.value}
-        onChange={handleChange}
-        disabled={disabled}
-        readOnly={readOnly}
-        loading={state.loading}
-        required={state.required}
-        title={state.meta.title}
-        description={state.meta.description}
-        placeholder={state.meta.placeholder}
-        label={state.meta.label}
-        options={options}
-        errors={state.errors}
-        extra={state.meta.extra}
-        displayType={fieldDisplayType}
-        labelWidth={fieldLabelWidth}
-        column={fieldColumn}
-        form={form}
-        dependValues={dependValues}
-        items={state.meta.items}
-        {...state.props}
-      />
+      {control}
     </div>
   );
 }

package/src/components/{NexusFormProvider.tsx → nexus-form-provider.tsx}

@@ -1,9 +1,9 @@
 import type { NexusEngine } from '@xbeeant/form-engine';
 import type { ReactNode } from 'react';
 import { useMemo } from 'react';
-import { NexusContext } from '../contexts/NexusContext';
-import type { FormController } from './FormController';
-import type { NexusFormConfig } from './NexusForm';
+import { NexusContext } from '../contexts/nexus-context';
+import type { FormController } from './form-controller';
+import type { NexusFormConfig } from './nexus-form';
 
 interface NexusFormProviderProps {
   engine: NexusEngine;

package/src/components/{NexusForm.tsx → nexus-form.tsx}

@@ -1,16 +1,23 @@
-import type { NexusSchema } from '@xbeeant/form-engine';
+import type { NexusComponent, NexusSchema } from '@xbeeant/form-engine';
 import type { CSSProperties, ReactNode, SubmitEvent } from 'react';
 import {
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useSyncExternalStore,
 } from 'react';
-
-import { renderTreeNode } from '../utils/renderTreeNode';
-import type { FormController } from './FormController';
-import { NexusFormProvider } from './NexusFormProvider';
+import { useFormSubmitting } from '../hooks';
+import {
+  clearPersisted,
+  loadPersisted,
+  type PersistOptions,
+  savePersisted,
+} from '../utils/persist';
+import { renderTreeNode } from '../utils/render-tree-node';
+import type { FormController } from './form-controller';
+import { NexusFormProvider } from './nexus-form-provider';
 
 // ────────────────────────────────────────────────────────────────────────────
 // Form 布局配置
@@ -31,10 +38,16 @@ export interface NexusFormConfig {
   readOnly?: boolean;
   /** 表单每行显示多少列 */
   column?: number;
+  /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+  locale?: string;
 }
 
 export interface NexusFormProps {
-  /** Form 实例，由 useForm() 创建 */
+  /**
+   * Form 实例，由 useForm() 创建。同一 form 引用 = 同一引擎宿主（组件/插件注册共享）；
+   * 每个 NexusForm 挂载自动获得独立实例（schema/值/订阅互不影响），
+   * form 的 API（getValues/setValues/submit...）聚合作用于全部实例。
+   */
   form: FormController;
   /** Schema 定义 */
   schema?: NexusSchema;
@@ -44,10 +57,19 @@ export interface NexusFormProps {
   widgets?: Record<string, (props: any) => ReactNode>;
   /** 额外注册的 layout */
   layouts?: Record<string, (props: any) => ReactNode>;
+  /** 字段包裹组件（UI 无关，Renderer 层注入；渲染层默认包裹所有 widget，label=false 时跳过） */
+  fieldWrapper?: NexusComponent;
   /** 提交成功回调 */
   onFinish?: (formData: Record<string, unknown>) => void | Promise<void>;
   /** 校验失败回调 */
   onFinishFailed?: (errors: Map<string, string[]>) => void;
+  /**
+   * 表单首次加载回调：非空 schema 首次传入并完成渲染后执行一次
+   * - undefined / null / {}（无 properties）均视为「空」schema，不触发
+   * - schema 由空变为非空时，于首个非空渲染提交后触发
+   * - 后续 schema 变更不重复触发
+   */
+  onMount?: () => void;
   /** 是否显示默认 footer（提交/重置按钮），或自定义 footer */
   footer?: boolean | ReactNode;
   /** 自定义类名 */
@@ -70,12 +92,37 @@ export interface NexusFormProps {
       changedPath?: string,
     ) => void;
   };
+  /**
+   * 表单值变化回调（x-render onValuesChange 对齐）
+   * 任意字段值变化时触发，参数为 (changedValue, allValues, changedPath)
+   * 与 watch: { '#': fn } 语义等价，但作为标准回调 API 提供
+   */
+  onValuesChange?: (
+    changedValue: unknown,
+    allValues: Record<string, unknown>,
+    changedPath: string,
+  ) => void;
   /**
    * 提交时是否移除 hidden 字段数据，默认 true
    * - true: submit/getValues 不包含 hidden 字段
    * - false: submit/getValues 包含所有字段（含 hidden）
    */
   removeHiddenData?: boolean;
+  /**
+   * 提交时递归移除空值（undefined/null/''，ProForm omitNil 对齐）
+   * 与 form.submit({ omitNil: true }) / form.getValues(paths, { omitNil: true }) 等价
+   */
+  omitNil?: boolean;
+  /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+  locale?: string;
+  /**
+   * 表单草稿持久化：值变化时自动保存到 Web Storage，下次挂载自动恢复
+   * @example
+   * ```tsx
+   * <NexusForm persist={{ key: 'apply-form', storage: 'localStorage' }} />
+   * ```
+   */
+  persist?: PersistOptions;
 
   // ── 表单布局配置 ──────────────────────────────────────────────────────
   /** label 列配置（由 ui 层 Form.Item 消费） */
@@ -105,8 +152,10 @@ export function NexusForm({
   initialValues,
   widgets,
   layouts,
+  fieldWrapper,
   onFinish,
   onFinishFailed,
+  onMount,
   footer = false,
   className,
   style,
@@ -119,10 +168,24 @@ export function NexusForm({
   readOnly,
   column,
   watch,
+  onValuesChange,
   removeHiddenData = true,
+  omitNil = false,
+  locale,
+  persist,
 }: NexusFormProps) {
-  const engine = form._getEngine();
+  // 实例视图引擎：同一 form 挂载的每个 NexusForm 自动获得独立实例
+  // （schema/值/订阅互不影响）；实例标识由 useId 内部生成，用户不感知 instanceId。
+  // 同一 form = 同一引擎宿主（组件/插件注册共享），不同 schema = 不同实例状态。
+  const instanceKey = useId();
+  const engine = useMemo(
+    () => form._useInstance(instanceKey),
+    [form, instanceKey],
+  );
   const formElRef = useRef<HTMLFormElement | null>(null);
+  // persist 配置经 ref 持有：保存回调不随配置对象变化重建订阅
+  const persistRef = useRef<PersistOptions | undefined>(persist);
+  persistRef.current = persist;
 
   // Schema 顶层配置作为默认值，props 优先级更高
   const finalDisplayType = displayType ?? schema?.displayType ?? 'row';
@@ -131,16 +194,20 @@ export function NexusForm({
   const finalLabelWidth = labelWidth ?? schema?.labelWidth;
   const finalReadOnly = readOnly ?? schema?.readOnly ?? false;
   const finalColumn = column ?? schema?.column;
+  const finalLocale = locale ?? schema?.locale ?? engine.getLocale();
 
   // 注册额外 widgets / layouts（仅首次或引用变化时）
   useEffect(() => {
     if (widgets) {
       engine.registerWidgets(widgets);
     }
+    if (fieldWrapper) {
+      engine.registerFieldWrapper(fieldWrapper);
+    }
     if (layouts) {
       engine.registerLayouts(layouts);
     }
-  }, [engine, widgets, layouts]);
+  }, [engine, widgets, layouts, fieldWrapper]);
 
   // schema 变化时重新初始化
   // 注意：initialValues 仅在首次挂载时使用，避免每次渲染都 re-init 导致
@@ -152,7 +219,11 @@ export function NexusForm({
       return;
     }
     if (isFirstInitRef.current) {
-      engine.init(schema, initialValuesRef.current);
+      // 草稿持久化：恢复已保存草稿（优先于 initialValues）
+      const persisted = persistRef.current
+        ? loadPersisted(persistRef.current)
+        : undefined;
+      engine.init(schema, persisted ?? initialValuesRef.current);
       isFirstInitRef.current = false;
     } else {
       // schema 变化：保留当前已填数据，而非重置为 initialValues
@@ -161,34 +232,99 @@ export function NexusForm({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [engine, schema]);
 
+  // 草稿持久化：store 版本变化（任意数据变更）时防抖保存
+  // 用持久化身份（storage:key）驱动订阅：开关切换 / 换 key 时重建订阅，
+  // 而 persist 对象本身每次渲染重建不影响订阅稳定性
+  const persistIdentity = persist
+    ? `${persist.storage ?? 'localStorage'}:${persist.key}`
+    : null;
+  useEffect(() => {
+    const options = persistIdentity ? persistRef.current : undefined;
+    if (!options) {
+      return;
+    }
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const debounce = options.debounce ?? 300;
+    const unsub = engine.subscribeStore(() => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(() => {
+        savePersisted(options, engine.getFormData());
+      }, debounce);
+    });
+    return () => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      unsub();
+    };
+  }, [engine, persistIdentity]);
+
+  // onMount：首次传入「非空」schema 并完成渲染后执行一次
+  // undefined / null / {}（无任何键）均视为空 schema，不触发；
+  // schema 由空变为非空时，于首个非空渲染提交（useEffect）后触发。
+  const onMountRef = useRef(onMount);
+  onMountRef.current = onMount;
+  const onMountFiredRef = useRef(false);
+  const isSchemaEmpty =
+    !schema || (typeof schema === 'object' && Object.keys(schema).length === 0);
+  useEffect(() => {
+    if (onMountFiredRef.current || isSchemaEmpty) {
+      return;
+    }
+    onMountFiredRef.current = true;
+    onMountRef.current?.();
+  }, [isSchemaEmpty]);
+
   // 绑定 form controller
   // 使用 ref 持有 onFinish / onFinishFailed，避免每次 re-render 都造成绑定逻辑重复执行
   const onFinishRef =
     useRef<(data: Record<string, unknown>) => void | Promise<void>>(noop);
   const onFinishFailedRef =
     useRef<(errors: Map<string, string[]>) => void>(noop);
-  onFinishRef.current = onFinish ?? noop;
+  onFinishRef.current = (data) => {
+    // persist 未配置时不参与提交流程；配置且 clearOnSubmit !== false 时清除草稿
+    const options = persistRef.current;
+    if (options && options.clearOnSubmit !== false) {
+      clearPersisted(options);
+    }
+    return onFinish?.(data);
+  };
   onFinishFailedRef.current = onFinishFailed ?? noop;
 
   // 只在挂载时绑定一次：传入「稳定的 getter」，让 FormController 在 submit 时读取最新回调
   useEffect(() => {
     form._bind(
+      instanceKey,
       formElRef.current,
       () => onFinishRef.current,
       () => onFinishFailedRef.current,
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [form]);
+  }, [form, instanceKey]);
 
-  // watch / removeHiddenData 变化时单独同步（不重置其他绑定）
+  // watch / removeHiddenData / onValuesChange 变化时单独同步（不重置其他绑定）
+  // onValuesChange 经 ref 持有：回调内容变化不重建订阅，仅内部引用更新
+  const onValuesChangeRef = useRef(onValuesChange);
+  onValuesChangeRef.current = onValuesChange;
   useEffect(() => {
-    form._syncConfig({ removeHiddenData, watch });
-  }, [form, removeHiddenData, watch]);
+    form._syncConfig(instanceKey, {
+      removeHiddenData,
+      omitNil,
+      watch,
+      onValuesChange: (changedValue, allValues, changedPath) =>
+        onValuesChangeRef.current?.(changedValue, allValues, changedPath),
+    });
+  }, [form, instanceKey, removeHiddenData, omitNil, watch]);
 
+  // 渲染树版本订阅：仅 Schema 结构变化（init/setSchema/reset）时重算 renderTree。
+  // 字段值/错误等数据变化只 bump store 版本（useFormData 消费），
+  // 不会触发 NexusForm 重渲染——各字段经字段级版本订阅精准重渲染。
   const _version = useSyncExternalStore(
-    engine.subscribeStore,
-    engine.getSnapshot,
-    engine.getSnapshot,
+    (cb) => engine.subscribeRender(cb),
+    () => engine.getRenderSnapshot(),
+    () => engine.getRenderSnapshot(),
   );
   // 依赖 _version：engine.init() / setSchema() 会 bump version，
   // 需要在此后重新读取 renderTree（首次渲染时 engine 尚未 init，renderTree 为空）
@@ -208,11 +344,14 @@ export function NexusForm({
   }, [form]);
 
   // footer 渲染
+  const submitting = useFormSubmitting(form);
   let footerNode: ReactNode = null;
   if (footer === true) {
     footerNode = (
       <div className='mt-4'>
-        <button type='submit'>提交</button>{' '}
+        <button type='submit' disabled={submitting}>
+          {submitting ? '提交中...' : '提交'}
+        </button>{' '}
         <button type='button' onClick={handleReset}>
           重置
         </button>
@@ -250,6 +389,7 @@ export function NexusForm({
       displayType: finalDisplayType,
       readOnly: finalReadOnly,
       column: finalColumn,
+      locale: finalLocale,
     }),
     [
       mergedLabelCol,
@@ -259,6 +399,7 @@ export function NexusForm({
       finalDisplayType,
       finalReadOnly,
       finalColumn,
+      finalLocale,
     ],
   );
 

package/src/components/{NexusLayout.tsx → nexus-layout.tsx}

@@ -2,14 +2,14 @@ import type { RenderLayoutNode } from '@xbeeant/form-engine';
 import type { CSSProperties } from 'react';
 import { useContext, useMemo } from 'react';
 
-import { GridContext } from '../contexts/GridContext';
+import { GridContext } from '../contexts/grid-context';
 import {
   LayoutConfigContext,
   type LayoutConfigContextValue,
-} from '../contexts/LayoutConfigContext';
-import { useNexusContext } from '../contexts/NexusContext';
-import { renderTreeNode } from '../utils/renderTreeNode';
-import { resolveColSpan } from '../utils/resolveColSpan';
+} from '../contexts/layout-config-context';
+import { useNexusContext } from '../contexts/nexus-context';
+import { renderTreeNode } from '../utils/render-tree-node';
+import { resolveColSpan } from '../utils/resolve-col-span';
 
 interface NexusLayoutProps {
   node: RenderLayoutNode;

package/src/components/{NexusObject.tsx → nexus-object.tsx}

@@ -2,9 +2,9 @@ import type { RenderObjectNode } from '@xbeeant/form-engine';
 import type { CSSProperties } from 'react';
 import { useContext, useState, useSyncExternalStore } from 'react';
 
-import { FieldInheritContext } from '../contexts/FieldInheritContext';
-import { useNexusContext } from '../contexts/NexusContext';
-import { renderTreeNode } from '../utils/renderTreeNode';
+import { FieldInheritContext } from '../contexts/field-inherit-context';
+import { useNexusContext } from '../contexts/nexus-context';
+import { renderTreeNode } from '../utils/render-tree-node';
 
 interface NexusObjectProps {
   node: RenderObjectNode;

package/src/contexts/{NexusContext.ts → nexus-context.ts}

@@ -1,7 +1,7 @@
 import type { NexusEngine } from '@xbeeant/form-engine';
 import { createContext, type ReactNode, useContext } from 'react';
 
-import type { FormController } from '../components/FormController';
+import type { FormController } from '../components/form-controller';
 
 // ────────────────────────────────────────────────────────────────────────────
 // Form 布局配置
@@ -22,6 +22,8 @@ export interface NexusFormConfig {
   readOnly?: boolean;
   /** 表单每行显示多少列 */
   column?: number;
+  /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+  locale?: string;
 }
 
 interface NexusContextValue {

package/src/hooks/index.ts

@@ -1,11 +1,12 @@
-export { useEngine } from './useEngine';
-export { useFieldState } from './useFieldState';
-export { useFieldValidator } from './useFieldValidator';
-export { useFieldValue } from './useFieldValue';
-export { useForm } from './useForm';
-export { useFormConfig } from './useFormConfig';
-export { useFormData } from './useFormData';
-export { useWatch } from './useWatch';
-export { useWatchAll } from './useWatchAll';
-export { useWatchMultiple } from './useWatchMultiple';
-export { useWatchState } from './useWatchState';
+export { useEngine } from './use-engine';
+export { useFieldState } from './use-field-state';
+export { useFieldValidator } from './use-field-validator';
+export { useFieldValue } from './use-field-value';
+export { useForm } from './use-form';
+export { useFormConfig } from './use-form-config';
+export { useFormData } from './use-form-data';
+export { useFormSubmitting } from './use-form-submitting';
+export { useWatch } from './use-watch';
+export { useWatchAll } from './use-watch-all';
+export { useWatchMultiple } from './use-watch-multiple';
+export { useWatchState } from './use-watch-state';

package/src/hooks/{useEngine.ts → use-engine.ts}

@@ -1,6 +1,6 @@
 import type { NexusEngine } from '@xbeeant/form-engine';
 
-import { useNexusContext } from '../contexts/NexusContext';
+import { useNexusContext } from '../contexts/nexus-context';
 
 export function useEngine(): NexusEngine {
   const { engine } = useNexusContext();

package/src/hooks/{useFieldState.ts → use-field-state.ts}

@@ -1,7 +1,7 @@
 import type { FieldState } from '@xbeeant/form-engine';
 import { useSyncExternalStore } from 'react';
 
-import { useNexusContext } from '../contexts/NexusContext';
+import { useNexusContext } from '../contexts/nexus-context';
 
 /**
  * useFieldState — 精准订阅单个字段状态

package/src/hooks/{useFieldValidator.ts → use-field-validator.ts}

@@ -24,7 +24,7 @@
 
 import type { NexusEngine, NexusFormInstance } from '@xbeeant/form-engine';
 import { useEffect, useRef } from 'react';
-import { useNexusContext } from '../contexts/NexusContext';
+import { useNexusContext } from '../contexts/nexus-context';
 
 export type FieldValidator = (
   value: unknown,

package/src/hooks/{useFieldValue.ts → use-field-value.ts}

@@ -1,6 +1,6 @@
 import { useSyncExternalStore } from 'react';
 
-import { useEngine } from './useEngine';
+import { useEngine } from './use-engine';
 
 /**
  * useFieldValue — 精准订阅单个字段值

package/src/hooks/{useFormConfig.ts → use-form-config.ts}

@@ -1,5 +1,5 @@
-import type { NexusFormConfig } from '../components/NexusForm';
-import { useNexusContext } from '../contexts/NexusContext';
+import type { NexusFormConfig } from '../components/nexus-form';
+import { useNexusContext } from '../contexts/nexus-context';
 
 /**
  * useFormConfig — 获取表单布局配置

package/src/hooks/{useFormData.ts → use-form-data.ts}

@@ -1,6 +1,6 @@
 import { useMemo, useSyncExternalStore } from 'react';
 
-import { useEngine } from './useEngine';
+import { useEngine } from './use-engine';
 
 /**
  * useFormData — 订阅整个表单数据
@@ -11,9 +11,9 @@ export function useFormData(): Record<string, unknown> {
   const engine = useEngine();
 
   const _version = useSyncExternalStore(
-    engine.subscribeStore,
-    engine.getSnapshot,
-    engine.getSnapshot,
+    (cb) => engine.subscribeStore(cb),
+    () => engine.getSnapshot(),
+    () => engine.getSnapshot(),
   );
   // biome-ignore lint/correctness/useExhaustiveDependencies: _version 是 formData 失效信号（engine 内部状态，静态分析不可见）
   return useMemo(() => engine.getFormData(), [engine, _version]);

package/src/hooks/use-form-submitting.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from 'react';
+
+import type { FormController } from '../components/form-controller';
+
+/**
+ * useFormSubmitting — 订阅表单提交中状态（formily submitting 对齐）
+ *
+ * submit() 全流程（校验 + onFinish）期间返回 true，供提交按钮展示 loading。
+ */
+export function useFormSubmitting(form: FormController): boolean {
+  return useSyncExternalStore(
+    (cb) => form.onSubmittingChange(cb),
+    () => form.getSubmitting(),
+    () => form.getSubmitting(),
+  );
+}