@xbeeant/form-engine-react 0.0.2 → 0.0.4

package/src/hooks/use-form.ts

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

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

@@ -3,28 +3,32 @@
 // 导出所有React组件、Hooks和类型定义，供上层应用使用
 // ============================================================================
 
-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';
+import './styles.css';
 
-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 { 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/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/styles.css

@@ -0,0 +1,6 @@
+/* Renderer 样式入口（Tailwind CSS v4）
+ * 仅引入 theme + utilities（不引入 preflight），随构建产物输出为 index.css，
+ * 供未接入 Tailwind 的宿主应用使用；已接入 Tailwind 的应用可忽略该文件
+ */
+@import "tailwindcss/theme";
+@import "tailwindcss/utilities";

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 {
+    // 静默失败
+  }
+}

package/src/utils/{renderTreeNode.tsx → render-tree-node.tsx}

@@ -1,9 +1,9 @@
 import type { RenderTreeNode } from '@xbeeant/form-engine';
 import type { ReactElement } from 'react';
 
-import { NexusField } from '../components/NexusField';
-import { NexusLayout } from '../components/NexusLayout';
-import { NexusObject } from '../components/NexusObject';
+import { NexusField } from '../components/nexus-field';
+import { NexusLayout } from '../components/nexus-layout';
+import { NexusObject } from '../components/nexus-object';
 
 /**
  * renderTreeNode — 递归渲染

package/src/utils/{resolveColSpan.ts → resolve-col-span.ts}

@@ -1,4 +1,4 @@
-import type { GridContextValue } from '../contexts/GridContext';
+import type { GridContextValue } from '../contexts/grid-context';
 
 /**
  * resolveColSpan — 统一解析子项在父 Grid 中的跨列数

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/components/FormController.ts

@@ -1,271 +0,0 @@
-import type {
-  FieldState,
-  NexusFormInstance,
-  NexusSchema,
-} from '@xbeeant/form-engine';
-import { AsyncValidatorPlugin, NexusEngine } from '@xbeeant/form-engine';
-import type { RefObject } from 'react';
-
-/**
- * FormController — 包裹 Engine，暴露 Form 实例 API
- */
-export class FormController implements NexusFormInstance {
-  private engine: NexusEngine;
-  private formElementRef: RefObject<HTMLFormElement | null>;
-  /** 稳定的 getter：每次 submit 执行时从外部 ref 读取最新的 onFinish/onFinishFailed 回调 */
-  private getOnFinish: () => (
-    data: Record<string, unknown>,
-  ) => void | Promise<void>;
-  private getOnFinishFailed: () => (errors: Map<string, string[]>) => void;
-  private removeHiddenData: boolean = true;
-  private watchers: Map<
-    string,
-    (value: unknown, allValues: Record<string, unknown>) => void
-  > = new Map();
-  private globalWatcher:
-    | ((
-        value: Record<string, unknown>,
-        allValues: Record<string, unknown>,
-        changedPath?: string,
-      ) => void)
-    | null = null;
-
-  constructor(engine?: NexusEngine) {
-    this.engine = engine ?? new NexusEngine();
-    // 默认注入异步校验器插件：useFieldValidator / registerFieldValidator
-    // 注册的异步校验器即可在字段值变化时被触发（防抖调度，与默认 'change' trigger 对齐）。
-    // 外部已注入同名插件时不重复注入（hasPlugin 幂等）。
-    if (!this.engine.hasPlugin('async-validator')) {
-      this.engine.use(new AsyncValidatorPlugin(this.engine));
-    }
-    this.formElementRef = {
-      current: null,
-    } as RefObject<HTMLFormElement | null>;
-    this.getOnFinish = () => () => {};
-    this.getOnFinishFailed = () => () => {};
-  }
-
-  /** 内部：首次绑定表单 DOM + 回调 getter（由 NexusForm 在挂载时调用一次） */
-  _bind(
-    formEl: HTMLFormElement | null,
-    getOnFinish: () => (data: Record<string, unknown>) => void | Promise<void>,
-    getOnFinishFailed: () => (errors: Map<string, string[]>) => void,
-  ): void {
-    (this.formElementRef as { current: HTMLFormElement | null }).current =
-      formEl;
-    this.getOnFinish = getOnFinish;
-    this.getOnFinishFailed = getOnFinishFailed;
-    // 注册值变更回调到 Engine，只需一次（回调闭包引用了稳定的实例）
-    this.engine.registerOnFieldValueChange((path, value) =>
-      this._onFieldValueChange(path, value),
-    );
-  }
-
-  /** 内部：同步 watch / removeHiddenData 配置（由 NexusForm 在它们变化时调用） */
-  _syncConfig(config: {
-    removeHiddenData?: boolean;
-    watch?: {
-      [path: string]: (
-        value: unknown,
-        allValues: Record<string, unknown>,
-        changedPath?: string,
-      ) => void;
-    };
-  }): void {
-    if (config.removeHiddenData !== undefined) {
-      this.removeHiddenData = config.removeHiddenData;
-    }
-    if (config.watch) {
-      this.watchers.clear();
-      this.globalWatcher = null;
-      for (const [path, fn] of Object.entries(config.watch)) {
-        if (path === '#') {
-          this.globalWatcher = fn;
-        } else {
-          this.watchers.set(path, fn);
-        }
-      }
-    }
-  }
-
-  /** 内部：值变更时调用（由 Engine 通知） */
-  _onFieldValueChange(path: string, value: unknown): void {
-    const allValues = this.engine.getFormData();
-    const globalData = this.removeHiddenData
-      ? allValues
-      : this.engine.getAllFormData();
-
-    // 全局 watcher（# 监听所有字段变化，value 即为全部表单值；
-    // 第三参携带本次实际变更的字段路径，供清空值场景区分「未赋值默认值」与「用户主动清空」）
-    if (this.globalWatcher) {
-      this.globalWatcher(globalData, globalData, path);
-    }
-    // 路径匹配的 watcher
-    const fn = this.watchers.get(path);
-    if (fn) {
-      fn(value, globalData);
-    }
-  }
-
-  /** 内部：获取 Engine 实例 */
-  _getEngine(): NexusEngine {
-    return this.engine;
-  }
-
-  async submit(): Promise<void> {
-    const errors = await this.engine.validate();
-    if (errors.size > 0) {
-      this.focusFirstError(errors);
-      this.getOnFinishFailed()?.(errors);
-      return;
-    }
-    const formData = this.removeHiddenData
-      ? this.engine.getFormData()
-      : this.engine.getAllFormData();
-    await this.getOnFinish()?.(formData);
-  }
-
-  /**
-   * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），
-   * 滚动入视并聚焦其内部可交互控件。
-   */
-  private focusFirstError(errors: Map<string, string[]>): void {
-    const formEl = this.formElementRef.current;
-    if (!formEl || errors.size === 0) {
-      return;
-    }
-
-    const errorPaths = new Set(errors.keys());
-
-    const focus = () => {
-      const fieldEls =
-        formEl.querySelectorAll<HTMLElement>('[data-nexus-field]');
-      for (const el of Array.from(fieldEls)) {
-        const path = el.getAttribute('data-nexus-field');
-        if (!path || !errorPaths.has(path)) {
-          continue;
-        }
-
-        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        const focusable = el.querySelector<HTMLElement>(
-          'input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
-        );
-        focusable?.focus();
-        return;
-      }
-    };
-
-    // 等待 React 将错误态刷到 DOM 后再定位，保证错误提示已可见
-    requestAnimationFrame(focus);
-  }
-
-  resetFields(): void {
-    this.engine.reset();
-  }
-
-  setErrorFields(errors: Array<{ path: string; errors: string[] }>): void {
-    this.engine.setErrorFields(errors);
-  }
-
-  setValues(values: Record<string, unknown>): void {
-    this.engine.setFieldValues(values);
-  }
-
-  setValueByPath(path: string, value: unknown): void {
-    this.engine.setFieldValue(path, value);
-  }
-
-  setSchemaByPath(path: string, patch: Record<string, unknown>): void {
-    this.engine.setSchemaByPath(path, patch);
-  }
-
-  setSchema(schema: NexusSchema): void {
-    this.engine.setSchema(schema);
-  }
-
-  getValues(paths?: string[]): Record<string, unknown> {
-    return this.engine.getFormData(paths);
-  }
-
-  getHiddenValues(): Record<string, unknown> {
-    return this.engine.getHiddenValues();
-  }
-
-  /** 获取所有字段值（含 hidden） */
-  getAllValues(): Record<string, unknown> {
-    return this.engine.getAllFormData();
-  }
-
-  getValueByPath(path: string): unknown {
-    return this.engine.getFieldValue(path);
-  }
-
-  /**
-   * 注册字段校验逻辑
-   * @param path 字段路径（如 'username'）
-   * @param validator 校验函数，返回错误消息数组（空数组表示通过）
-   */
-  registerValidator(
-    path: string,
-    validator: (
-      value: unknown,
-      formData: Record<string, unknown>,
-    ) => string[] | Promise<string[]>,
-  ): void {
-    // 注册到 Engine（validate 与 实时校验 统一由 Engine 执行）
-    this.engine.registerFieldValidator(path, validator);
-  }
-
-  /**
-   * 注销字段校验逻辑（按函数引用移除）
-   * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
-   */
-  unregisterValidator(
-    path: string,
-    validator: (
-      value: unknown,
-      formData: Record<string, unknown>,
-    ) => string[] | Promise<string[]>,
-  ): void {
-    this.engine.unregisterFieldValidator(path, validator);
-  }
-
-  /**
-   * 实时重校验指定字段（同步）
-   * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
-   */
-  revalidateField(path: string): void {
-    this.engine.validateField(path, { trigger: 'change' });
-  }
-
-  getSchema(): NexusSchema | null {
-    return this.engine.getSchema();
-  }
-
-  removeErrorField(path: string): void {
-    this.engine.removeErrorField(path);
-  }
-
-  scrollToPath(path: string): void {
-    const el = this.formElementRef.current?.querySelector(
-      `[data-nexus-field="${path}"]`,
-    );
-    el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
-  }
-
-  getFieldError(path: string): string[] {
-    return this.engine.getFieldError(path);
-  }
-
-  getFieldsError(): Map<string, string[]> {
-    return this.engine.getFieldsError();
-  }
-
-  validateFields(paths?: string[]): Promise<Map<string, string[]>> {
-    return this.engine.validate(paths);
-  }
-
-  getFieldState(path: string): FieldState | undefined {
-    return this.engine.getFieldState(path);
-  }
-}

package/src/hooks/useForm.ts

@@ -1,15 +0,0 @@
-import type { NexusEngine } from '@xbeeant/form-engine';
-import { useRef } from 'react';
-
-import { FormController } from '../components/FormController';
-
-/**
- * useForm — 创建 Form 实例
- */
-export function useForm(engine?: NexusEngine): [FormController] {
-  const formRef = useRef<FormController | null>(null);
-  if (!formRef.current) {
-    formRef.current = new FormController(engine);
-  }
-  return [formRef.current];
-}