@xbeeant/form-engine-react 0.0.1

package/src/hooks/useFieldValidator.ts

@@ -0,0 +1,123 @@
+// ────────────────────────────────────────────────────────────────────────────
+// useFieldValidator — 在 widget 组件内命令式注册字段校验规则
+//
+// 对齐 x-render 子表单内部校验思路：校验逻辑写在 UI 组件内部，
+// 而非全部下沉到 Schema。组件通过自身 dataPath + form 实例注册校验器，
+// 校验器可访问组件闭包内状态（实现与组件 state 联动）。
+//
+// 使用：
+// ```tsx
+// export const confirmPasswordWidget = withFormItem((props) => {
+//   const { dataPath, form, value } = props;
+//   const [strict, setStrict] = useState(false);
+//   useFieldValidator(form, dataPath, (val, formData) => {
+//     if (strict && val && val !== formData.password) {
+//       return ['两次输入的密码不一致'];
+//     }
+//     return [];
+//   }, { dependsOn: ['password'], deps: [strict] });
+//   const { dependValues: _dv, path: _p, ...rest } = props;
+//   return <Input.Password value={value} {...rest} />;
+// });
+// ```
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { NexusEngine, NexusFormInstance } from '@xbeeant/form-engine';
+import { useEffect, useRef } from 'react';
+import { useNexusContext } from '../contexts/NexusContext';
+
+export type FieldValidator = (
+  value: unknown,
+  formData: Record<string, unknown>,
+) => string[] | Promise<string[]>;
+
+export interface UseFieldValidatorOptions {
+  /**
+   * 依赖字段路径列表。这些字段变化时自动对目标字段重校验，
+   * 实现「组件内注册的跨字段校验」与依赖字段的实时联动
+   * （等价于 schema 中 validate 表达式的依赖图联动）。
+   */
+  dependsOn?: string[];
+  /**
+   * 校验器闭包依赖的组件 state（useEffect 语义）。
+   * 任意依赖值变化时，校验器会重新注册，新闭包捕获最新的组件 state，
+   * 保证校验逻辑读到的是当前渲染的 state，而不是注册时刻的陈旧值。
+   *
+   * 用法：
+   * ```tsx
+   * const [strict, setStrict] = useState(false);
+   * useFieldValidator(form, dataPath, (val, formData) => {
+   *   if (strict && val && val !== formData.password) { ... }
+   * }, { deps: [strict] });
+   * ```
+   */
+  deps?: ReadonlyArray<unknown>;
+}
+
+/**
+ * 在 widget 组件内注册字段校验规则
+ *
+ * - 挂载时调用 form.registerValidator(path, validator)
+ * - 卸载时调用 form.unregisterValidator 清理，避免校验器累积
+ * - validator 通过 ref 持有最新闭包；deps 变化时 effect 重跑，
+ *   重新注册捕获最新组件 state 的新闭包（useEffect 语义），
+ *   校验逻辑总能读到当前渲染的组件 state
+ * - 传入 dependsOn 时，订阅依赖字段变化并实时重校验目标字段
+ *
+ * @param form - 表单实例（widget 的 props.form）
+ * @param path - 字段路径（widget 的 props.dataPath）
+ * @param validator - 校验函数，返回错误消息数组（空数组 = 通过）
+ * @param options - 配置（dependsOn 依赖字段联动 / deps 闭包依赖的组件 state）
+ */
+export function useFieldValidator(
+  form: NexusFormInstance | undefined,
+  path: string | undefined,
+  validator: FieldValidator,
+  options?: UseFieldValidatorOptions,
+): void {
+  const { engine } = useNexusContext();
+
+  // 用 ref 保存最新 validator/options，避免外部 inline 函数导致每次渲染重注册
+  const validatorRef = useRef(validator);
+  validatorRef.current = validator;
+  const dependsRef = useRef(options?.dependsOn);
+  dependsRef.current = options?.dependsOn;
+  const deps = options?.deps;
+
+  // 注册 / 注销校验器
+  // deps 变化（useEffect 语义）时 effect 重跑：unregister 旧闭包 → register 新闭包，
+  // 新闭包捕获 deps 中声明的最新组件 state。
+  useEffect(() => {
+    if (!form || !path) {
+      return;
+    }
+    const current = validatorRef.current;
+    form.registerValidator(path, current);
+    return () => {
+      form.unregisterValidator(path, current);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [form, path, ...(deps ?? [])]);
+
+  // 订阅依赖字段变化 → 实时重校验目标字段（跨字段联动）
+  useEffect(() => {
+    if (!path || !dependsRef.current || dependsRef.current.length === 0) {
+      return;
+    }
+    const engineSafe = engine as NexusEngine | undefined;
+    if (!engineSafe) {
+      return;
+    }
+    const target = path;
+    const unsubscribers = dependsRef.current.map((dep) =>
+      engineSafe.subscribeField(dep, () => {
+        form?.revalidateField(target);
+      }),
+    );
+    return () => {
+      for (const unsub of unsubscribers) {
+        unsub();
+      }
+    };
+  }, [engine, form, path]);
+}

package/src/hooks/useFieldValue.ts

@@ -0,0 +1,20 @@
+import { useSyncExternalStore } from 'react';
+
+import { useEngine } from './useEngine';
+
+/**
+ * useFieldValue — 精准订阅单个字段值
+ *
+ * 按路径精准订阅：仅该字段版本变化时重渲染
+ */
+export function useFieldValue<T = unknown>(path: string): T | undefined {
+  const engine = useEngine();
+
+  useSyncExternalStore(
+    (onStoreChange) => engine.subscribeField(path, onStoreChange),
+    () => engine.getFieldVersion(path),
+    () => engine.getFieldVersion(path),
+  );
+
+  return engine.getFieldValue(path) as T | undefined;
+}

package/src/hooks/useForm.ts

@@ -0,0 +1,15 @@
+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];
+}

package/src/hooks/useFormConfig.ts

@@ -0,0 +1,10 @@
+import type { NexusFormConfig } from '../components/NexusForm';
+import { useNexusContext } from '../contexts/NexusContext';
+
+/**
+ * useFormConfig — 获取表单布局配置
+ */
+export function useFormConfig(): NexusFormConfig {
+  const { config } = useNexusContext();
+  return config;
+}

package/src/hooks/useFormData.ts

@@ -0,0 +1,20 @@
+import { useMemo, useSyncExternalStore } from 'react';
+
+import { useEngine } from './useEngine';
+
+/**
+ * useFormData — 订阅整个表单数据
+ *
+ * 用 version 作为快照依赖，避免 getFormData() 每次返回新对象引用导致的无谓重渲染
+ */
+export function useFormData(): Record<string, unknown> {
+  const engine = useEngine();
+
+  const _version = useSyncExternalStore(
+    engine.subscribeStore,
+    engine.getSnapshot,
+    engine.getSnapshot,
+  );
+  // biome-ignore lint/correctness/useExhaustiveDependencies: _version 是 formData 失效信号（engine 内部状态，静态分析不可见）
+  return useMemo(() => engine.getFormData(), [engine, _version]);
+}

package/src/hooks/useNexusContext.ts

@@ -0,0 +1,24 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Context
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { NexusEngine } from '@xbeeant/form-engine';
+import { createContext, useContext } from 'react';
+import type { FormController } from '../components/FormController';
+import type { NexusFormConfig } from '../components/NexusForm';
+
+interface NexusContextValue {
+  engine: NexusEngine;
+  config: NexusFormConfig;
+  form: FormController;
+}
+
+export const NexusContext = createContext<NexusContextValue | null>(null);
+
+export function useNexusContext(): NexusContextValue {
+  const ctx = useContext(NexusContext);
+  if (!ctx) {
+    throw new Error('[NexusField] Must be used within <NexusFormProvider>');
+  }
+  return ctx;
+}

package/src/hooks/useWatch.ts

@@ -0,0 +1,83 @@
+import type { NexusEngine } from '@xbeeant/form-engine';
+import { useEffect, useRef } from 'react';
+
+/**
+ * useWatch Hook - 监听单个字段值变化
+ *
+ * @param engine - NexusEngine实例
+ * @param path - 字段路径
+ * @param callback - 变化回调函数
+ * @param deep - 是否深度比较值（默认false，仅浅比较）
+ *
+ * @example
+ * ```tsx
+ * // 监听单个字段
+ * const name = useWatch(engine, 'profile.name', (value) => {
+ *   console.log('Name changed:', value);
+ * });
+ *
+ * // 深度比较对象
+ * const profile = useWatch(engine, 'profile', (value) => {
+ *   console.log('Profile changed:', value);
+ * }, { deep: true });
+ * ```
+ */
+export function useWatch(
+  engine: NexusEngine | null,
+  path: string,
+  callback: (value: unknown) => void,
+  options?: {
+    deep?: boolean;
+  },
+): unknown {
+  const { deep = false } = options || {};
+  const lastValueRef = useRef<unknown>(undefined);
+
+  // callback 通过 ref 持有最新引用：外部 inline 回调不会导致每次渲染重新订阅
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!engine) {
+      return;
+    }
+
+    const value = engine.getFieldValue(path);
+
+    // 初始化时立即执行一次
+    if (lastValueRef.current === undefined) {
+      lastValueRef.current = value;
+    }
+
+    // 比较值是否变化
+    const shouldCall = deep
+      ? JSON.stringify(value) !== JSON.stringify(lastValueRef.current)
+      : value !== lastValueRef.current;
+
+    if (shouldCall) {
+      lastValueRef.current = value;
+      callbackRef.current(value);
+    }
+
+    // 订阅字段变化
+    const unsubscribe = engine.subscribe(path, (state) => {
+      const newValue = state.value;
+
+      // 比较值是否变化
+      const shouldUpdate = deep
+        ? JSON.stringify(newValue) !== JSON.stringify(lastValueRef.current)
+        : newValue !== lastValueRef.current;
+
+      if (shouldUpdate) {
+        lastValueRef.current = newValue;
+        callbackRef.current(newValue);
+      }
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [engine, path, deep]);
+
+  return lastValueRef.current;
+}

package/src/hooks/useWatchAll.ts

@@ -0,0 +1,77 @@
+import type { NexusEngine } from '@xbeeant/form-engine';
+import { useEffect, useRef } from 'react';
+
+/**
+ * useWatchAll Hook - 监听整个表单数据变化
+ *
+ * @param engine - NexusEngine实例
+ * @param callback - 变化回调函数
+ * @param deep - 是否深度比较值（默认false，仅浅比较）
+ *
+ * @example
+ * ```tsx
+ * // 监听整个表单
+ * useWatchAll(engine, (formData) => {
+ *   console.log('Form data changed:', formData);
+ * }, { deep: true });
+ * ```
+ */
+export function useWatchAll(
+  engine: NexusEngine | null,
+  callback: (formData: Record<string, unknown>) => void,
+  options?: {
+    deep?: boolean;
+  },
+): Record<string, unknown> {
+  const { deep = false } = options || {};
+  const lastFormDataRef = useRef<Record<string, unknown>>({});
+  const formDataRef = useRef<Record<string, unknown>>({});
+
+  // callback 通过 ref 持有最新引用：外部 inline 回调不会导致每次渲染重新订阅
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!engine) {
+      return;
+    }
+
+    const formData = engine.getFormData();
+    lastFormDataRef.current = formData;
+    formDataRef.current = formData;
+    callbackRef.current(formData);
+
+    const unsubscribe = engine.subscribeAll((newFormData) => {
+      if (deep) {
+        const changed =
+          JSON.stringify(newFormData) !==
+          JSON.stringify(lastFormDataRef.current);
+        if (changed) {
+          lastFormDataRef.current = newFormData;
+          formDataRef.current = newFormData;
+          callbackRef.current(newFormData);
+        }
+      } else {
+        // 简单浅比较
+        let changed = false;
+        for (const key in newFormData) {
+          if (newFormData[key] !== lastFormDataRef.current[key]) {
+            changed = true;
+            break;
+          }
+        }
+        if (changed) {
+          lastFormDataRef.current = newFormData;
+          formDataRef.current = newFormData;
+          callbackRef.current(newFormData);
+        }
+      }
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [engine, deep]);
+
+  return formDataRef.current;
+}

package/src/hooks/useWatchMultiple.ts

@@ -0,0 +1,86 @@
+import type { NexusEngine } from '@xbeeant/form-engine';
+import { useEffect, useRef } from 'react';
+
+/**
+ * useWatchMultiple Hook - 监听多个字段值变化
+ *
+ * @param engine - NexusEngine实例
+ * @param paths - 字段路径数组
+ * @param callback - 变化回调函数
+ * @param deep - 是否深度比较值（默认false，仅浅比较）
+ *
+ * @example
+ * ```tsx
+ * // 监听多个字段
+ * const values = useWatchMultiple(engine, ['name', 'email', 'age'], (values) => {
+ *   console.log('Values changed:', values);
+ * }, { deep: true });
+ * ```
+ */
+export function useWatchMultiple(
+  engine: NexusEngine | null,
+  paths: string[],
+  callback: (values: Record<string, unknown>) => void,
+  options?: {
+    deep?: boolean;
+  },
+): Record<string, unknown> {
+  const { deep = false } = options || {};
+  const lastValuesRef = useRef<Record<string, unknown>>({});
+  const valuesRef = useRef<Record<string, unknown>>({});
+
+  // callback / paths 通过 ref 持有最新引用：
+  // - inline 回调不会导致每次渲染重新订阅
+  // - 数组字面量（每次渲染新建引用）不会导致重复订阅
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+  const pathsRef = useRef(paths);
+  pathsRef.current = paths;
+  // 仅当路径列表内容变化时才重新订阅（顺序无关，排序后比较）
+  const pathsKey = [...paths].sort().join(',');
+
+  // pathsKey：路径列表内容变化的稳定信号（数组引用本身不稳定，不参与依赖比较）
+  // biome-ignore lint/correctness/useExhaustiveDependencies: paths 引用不稳定，以内容键 pathsKey 为准
+  useEffect(() => {
+    if (!engine) {
+      return;
+    }
+
+    // 初始化
+    const watchedPaths = pathsRef.current;
+    const initialValues: Record<string, unknown> = {};
+    for (const path of watchedPaths) {
+      initialValues[path] = engine.getFieldValue(path);
+    }
+    lastValuesRef.current = initialValues;
+    valuesRef.current = initialValues;
+
+    callbackRef.current(initialValues);
+
+    // 按路径精准订阅（依赖图 O(k) 通知），避免 subscribeAll 全表单扫描
+    const unsubscribe = watchedPaths.map((path) =>
+      engine.subscribe(path, (state) => {
+        const newValue = state.value;
+        const lastValue = lastValuesRef.current[path];
+
+        const changed = deep
+          ? JSON.stringify(newValue) !== JSON.stringify(lastValue)
+          : newValue !== lastValue;
+
+        if (changed) {
+          lastValuesRef.current[path] = newValue;
+          valuesRef.current = { [path]: newValue };
+          callbackRef.current(valuesRef.current);
+        }
+      }),
+    );
+
+    return () => {
+      for (const unsub of unsubscribe) {
+        unsub();
+      }
+    };
+  }, [engine, deep, pathsKey]);
+
+  return valuesRef.current;
+}

package/src/hooks/useWatchState.ts

@@ -0,0 +1,54 @@
+import type { FieldState, NexusEngine } from '@xbeeant/form-engine';
+import { useEffect, useRef } from 'react';
+
+/**
+ * useWatchState Hook - 监听单个字段状态变化
+ *
+ * @param engine - NexusEngine实例
+ * @param path - 字段路径
+ * @param callback - 状态变化回调函数
+ *
+ * @example
+ * ```tsx
+ * // 监听字段状态（visible/disabled/loading等）
+ * const isDisabled = useWatchState(engine, 'email', (state) => {
+ *   console.log('Disabled:', state.disabled);
+ *   console.log('Loading:', state.loading);
+ * });
+ * ```
+ */
+export function useWatchState(
+  engine: NexusEngine | null,
+  path: string,
+  callback: (state: FieldState) => void,
+): FieldState {
+  const stateRef = useRef<FieldState | undefined>(undefined);
+
+  // callback 通过 ref 持有最新引用：外部 inline 回调不会导致每次渲染重新订阅
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!engine) {
+      return;
+    }
+
+    const state = engine.getFieldState(path);
+    stateRef.current = state;
+
+    if (state) {
+      callbackRef.current(state);
+    }
+
+    const unsubscribe = engine.subscribe(path, (newState) => {
+      stateRef.current = newState;
+      callbackRef.current(newState);
+    });
+
+    return () => {
+      unsubscribe();
+    };
+  }, [engine, path]);
+
+  return stateRef.current || ({} as FieldState);
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// ============================================================================
+// React包入口文件
+// 导出所有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';
+
+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';

package/src/utils/renderTreeNode.tsx

@@ -0,0 +1,30 @@
+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';
+
+/**
+ * renderTreeNode — 递归渲染
+ */
+export function renderTreeNode(
+  node: RenderTreeNode,
+  index: number,
+): ReactElement {
+  if (node.type === 'field') {
+    return (
+      <NexusField
+        key={node.layoutKey || node.dataPath}
+        dataPath={node.dataPath}
+        layoutKey={node.layoutKey}
+      />
+    );
+  }
+  if (node.type === 'object') {
+    return (
+      <NexusObject key={`object-${node.layoutKey}-${index}`} node={node} />
+    );
+  }
+  return <NexusLayout key={`layout-${node.type}-${index}`} node={node} />;
+}

package/src/utils/resolveColSpan.ts

@@ -0,0 +1,18 @@
+import type { GridContextValue } from '../contexts/GridContext';
+
+/**
+ * resolveColSpan — 统一解析子项在父 Grid 中的跨列数
+ */
+export function resolveColSpan(
+  colSpan: number | undefined,
+  gridCtx: GridContextValue | null,
+): number | undefined {
+  if (colSpan !== undefined) {
+    return colSpan;
+  }
+
+  // 在 grid 容器内：把 24 栅格语义缩放到当前 column
+  if (gridCtx && gridCtx.column > 0) {
+    return Math.max(1, Math.round(gridCtx.column / 24));
+  }
+}