@xbeeant/form-engine-react 0.0.3 → 0.0.4

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,6 +57,8 @@ 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>;
   /** 校验失败回调 */
@@ -77,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 消费） */
@@ -112,6 +152,7 @@ export function NexusForm({
   initialValues,
   widgets,
   layouts,
+  fieldWrapper,
   onFinish,
   onFinishFailed,
   onMount,
@@ -127,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';
@@ -139,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 导致
@@ -160,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
@@ -169,6 +232,35 @@ 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）后触发。
@@ -191,28 +283,48 @@ export function NexusForm({
     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 为空）
@@ -232,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>
@@ -274,6 +389,7 @@ export function NexusForm({
       displayType: finalDisplayType,
       readOnly: finalReadOnly,
       column: finalColumn,
+      locale: finalLocale,
     }),
     [
       mergedLabelCol,
@@ -283,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(),
+  );
+}

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

@@ -1,19 +1,26 @@
 import { NexusEngine } from '@xbeeant/form-engine';
 import { useRef } from 'react';
 
-import { FormController } from '../components/FormController';
+import { FormController } from '../components/form-controller';
 
 /**
  * useForm — 创建 Form 实例
  *
- * 支持一个页面挂载多个表单实例：
- * - `useForm()`：独立实例（未注册，不参与跨表单联动）
+ * 一个 Form 绑定一个引擎宿主（引擎为独立实体）：
+ * - 同一 form 引用传给多个 NexusForm → 共享引擎宿主（组件/插件注册共享），
+ *   每个 NexusForm 挂载自动获得独立实例（schema/值/订阅互不影响），
+ *   form 的 API 聚合作用于全部实例
+ * - 需要完全独立的表单：各自 useForm()（独立引擎宿主）
+ *
+ * 支持：
+ * - `useForm()`：创建独立实例（引擎宿主内部创建，未注册，不参与跨表单联动）
  * - `useForm(formId)`：创建带 formId 的实例，自动注册到默认表单注册表，
  *   可通过 schema `crossForm` reaction / `engine.linkForm` 与其他表单联动
- * - `useForm(formId, engine)`：复用外部创建的引擎（如 `new NexusEngine({ formId })`）
+ * - `useForm(formId, engine)`：复用外部创建的引擎（如 `new NexusEngine({ formId })`），
+ *   实现多个 form 共享同一引擎宿主
  *
  * @param formId - 可选，表单实例唯一标识（跨表单联动寻址）
- * @param engine - 可选，外部引擎实例（缺省内部创建）
+ * @param engine - 可选，外部引擎宿主（缺省内部创建）
  */
 export function useForm(
   formId?: string,

package/src/hooks/{useNexusContext.ts → use-nexus-context.ts}

@@ -4,8 +4,8 @@
 
 import type { NexusEngine } from '@xbeeant/form-engine';
 import { createContext, useContext } from 'react';
-import type { FormController } from '../components/FormController';
-import type { NexusFormConfig } from '../components/NexusForm';
+import type { FormController } from '../components/form-controller';
+import type { NexusFormConfig } from '../components/nexus-form';
 
 interface NexusContextValue {
   engine: NexusEngine;

package/src/index.ts

@@ -5,28 +5,30 @@
 
 import './styles.css';
 
-export { FormController } from './components/FormController';
-export { NexusField } from './components/NexusField';
-export type { NexusFormConfig } from './components/NexusForm';
-export { NexusForm } from './components/NexusForm';
-export { NexusFormProvider } from './components/NexusFormProvider';
-export { NexusLayout } from './components/NexusLayout';
-export { NexusObject } from './components/NexusObject';
-export type { FieldInheritValue } from './contexts/FieldInheritContext';
-export { FieldInheritContext } from './contexts/FieldInheritContext';
-export type { GridContextValue } from './contexts/GridContext';
-export { GridContext } from './contexts/GridContext';
-export type { LayoutConfigContextValue } from './contexts/LayoutConfigContext';
-export { LayoutConfigContext } from './contexts/LayoutConfigContext';
+export { FormController } from './components/form-controller';
+export { NexusField } from './components/nexus-field';
+export type { NexusFormConfig, NexusFormProps } from './components/nexus-form';
+export { NexusForm } from './components/nexus-form';
+export { NexusFormProvider } from './components/nexus-form-provider';
+export { NexusLayout } from './components/nexus-layout';
+export { NexusObject } from './components/nexus-object';
+export type { FieldInheritValue } from './contexts/field-inherit-context';
+export { FieldInheritContext } from './contexts/field-inherit-context';
+export type { GridContextValue } from './contexts/grid-context';
+export { GridContext } from './contexts/grid-context';
+export type { LayoutConfigContextValue } from './contexts/layout-config-context';
+export { LayoutConfigContext } from './contexts/layout-config-context';
+export { NexusContext } from './contexts/nexus-context';
 
-export { useEngine } from './hooks/useEngine';
-export { useFieldState } from './hooks/useFieldState';
-export { useFieldValidator } from './hooks/useFieldValidator';
-export { useFieldValue } from './hooks/useFieldValue';
-export { useForm } from './hooks/useForm';
-export { useFormConfig } from './hooks/useFormConfig';
-export { useFormData } from './hooks/useFormData';
-export { useWatch } from './hooks/useWatch';
-export { useWatchAll } from './hooks/useWatchAll';
-export { useWatchMultiple } from './hooks/useWatchMultiple';
-export { useWatchState } from './hooks/useWatchState';
+export { useEngine } from './hooks/use-engine';
+export { useFieldState } from './hooks/use-field-state';
+export { useFieldValidator } from './hooks/use-field-validator';
+export { useFieldValue } from './hooks/use-field-value';
+export { useForm } from './hooks/use-form';
+export { useFormConfig } from './hooks/use-form-config';
+export { useFormData } from './hooks/use-form-data';
+export { useFormSubmitting } from './hooks/use-form-submitting';
+export { useWatch } from './hooks/use-watch';
+export { useWatchAll } from './hooks/use-watch-all';
+export { useWatchMultiple } from './hooks/use-watch-multiple';
+export { useWatchState } from './hooks/use-watch-state';

package/src/utils/omit-nil.ts

@@ -0,0 +1,24 @@
+/**
+ * omitNilDeep — 递归移除空值（undefined / null / ''）
+ *
+ * ProForm omitNil 对齐：提交/取值时过滤掉未填写的空值字段。
+ * - 对象：移除值为空的键（递归处理嵌套对象）
+ * - 数组：逐项递归处理（保留数组结构与长度）
+ * - 0 / false / NaN 等非空值保留
+ */
+export function omitNilDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => omitNilDeep(item));
+  }
+  if (value !== null && typeof value === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined || item === null || item === '') {
+        continue;
+      }
+      result[key] = omitNilDeep(item);
+    }
+    return result;
+  }
+  return value;
+}

package/src/utils/persist.ts

@@ -0,0 +1,88 @@
+/**
+ * 表单草稿持久化（NexusForm persist 选项实现）
+ *
+ * 将表单数据自动保存到 Web Storage（localStorage / sessionStorage），
+ * 下次挂载时自动恢复为初始值（草稿续填）。
+ *
+ * 约束：
+ * - 所有存储访问均 try/catch 包裹（SSR 无 window / Safari 隐私模式抛错）
+ * - 存储键为完整路径前缀，避免多表单实例冲突
+ * - 提交成功后默认清除草稿（clearOnSubmit: false 可关闭）
+ */
+
+export interface PersistOptions {
+  /** 存储键（必填，多表单实例需唯一） */
+  key: string;
+  /** 存储介质，默认 localStorage */
+  storage?: 'localStorage' | 'sessionStorage';
+  /** 保存防抖毫秒数，默认 300 */
+  debounce?: number;
+  /** 提交成功后清除草稿，默认 true */
+  clearOnSubmit?: boolean;
+}
+
+function getStorage(
+  storage?: 'localStorage' | 'sessionStorage',
+): Storage | undefined {
+  if (typeof window === 'undefined') {
+    return undefined;
+  }
+  try {
+    const target =
+      storage === 'sessionStorage'
+        ? window.sessionStorage
+        : window.localStorage;
+    // 隐私模式下访问可能抛错，统一降级为不持久化
+    target.setItem('__nexus_persist_probe__', '1');
+    target.removeItem('__nexus_persist_probe__');
+    return target;
+  } catch {
+    return undefined;
+  }
+}
+
+export function loadPersisted(
+  options: PersistOptions,
+): Record<string, unknown> | undefined {
+  const storage = getStorage(options.storage);
+  if (!storage) {
+    return undefined;
+  }
+  try {
+    const raw = storage.getItem(options.key);
+    if (!raw) {
+      return undefined;
+    }
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function savePersisted(
+  options: PersistOptions,
+  data: Record<string, unknown>,
+): void {
+  const storage = getStorage(options.storage);
+  if (!storage) {
+    return;
+  }
+  try {
+    storage.setItem(options.key, JSON.stringify(data));
+  } catch {
+    // 存储配额满 / 隐私模式：静默失败
+  }
+}
+
+export function clearPersisted(options: PersistOptions): void {
+  const storage = getStorage(options.storage);
+  if (!storage) {
+    return;
+  }
+  try {
+    storage.removeItem(options.key);
+  } catch {
+    // 静默失败
+  }
+}