@xbeeant/form-engine-react 0.0.1

package/src/components/NexusForm.tsx

@@ -0,0 +1,290 @@
+import type { NexusSchema } from '@xbeeant/form-engine';
+import type { CSSProperties, ReactNode, SubmitEvent } from 'react';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+import { renderTreeNode } from '../utils/renderTreeNode';
+import type { FormController } from './FormController';
+import { NexusFormProvider } from './NexusFormProvider';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Form 布局配置
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface NexusFormConfig {
+  /** label 列配置（由 ui 层 Form.Item 消费） */
+  labelCol?: Record<string, unknown>;
+  /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
+  labelWidth?: number | string;
+  /** 是否显示冒号 */
+  colon?: boolean | ReactNode;
+  /** 是否显示 label（默认 true） */
+  label?: boolean;
+  /** 表单布局方向 */
+  displayType?: 'row' | 'column' | 'inline';
+  /** 整个表单只读，所有字段以文本展示 */
+  readOnly?: boolean;
+  /** 表单每行显示多少列 */
+  column?: number;
+}
+
+export interface NexusFormProps {
+  /** Form 实例，由 useForm() 创建 */
+  form: FormController;
+  /** Schema 定义 */
+  schema?: NexusSchema;
+  /** 初始值 */
+  initialValues?: Record<string, unknown>;
+  /** 额外注册的 widget（与已注册的合并） */
+  widgets?: Record<string, (props: any) => ReactNode>;
+  /** 额外注册的 layout */
+  layouts?: Record<string, (props: any) => ReactNode>;
+  /** 提交成功回调 */
+  onFinish?: (formData: Record<string, unknown>) => void | Promise<void>;
+  /** 校验失败回调 */
+  onFinishFailed?: (errors: Map<string, string[]>) => void;
+  /** 是否显示默认 footer（提交/重置按钮），或自定义 footer */
+  footer?: boolean | ReactNode;
+  /** 自定义类名 */
+  className?: string;
+  /** 自定义样式 */
+  style?: CSSProperties;
+  /** 子节点 */
+  children?: ReactNode;
+  /**
+   * 表单值变化监听
+   * - key 为字段路径（如 'username'），值为回调函数
+   * - 使用 '#' 作为 key 可监听所有字段变化
+   * - 回调参数为 (value, allValues)；全局（'#'）监听额外提供第三参 changedPath，
+   *   即本次实际变更的字段路径（用于区分「未触碰的默认空值」与「用户主动清空」）
+   */
+  watch?: {
+    [path: string]: (
+      value: unknown,
+      allValues: Record<string, unknown>,
+      changedPath?: string,
+    ) => void;
+  };
+  /**
+   * 提交时是否移除 hidden 字段数据，默认 true
+   * - true: submit/getValues 不包含 hidden 字段
+   * - false: submit/getValues 包含所有字段（含 hidden）
+   */
+  removeHiddenData?: boolean;
+
+  // ── 表单布局配置 ──────────────────────────────────────────────────────
+  /** label 列配置（由 ui 层 Form.Item 消费） */
+  labelCol?: Record<string, unknown>;
+  /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
+  labelWidth?: number | string;
+  /** 是否显示冒号 */
+  colon?: boolean | ReactNode;
+  /** 是否显示 label（默认 true） */
+  label?: boolean;
+  /** 表单布局方向：'row' = horizontal, 'column' = vertical, 'inline' = inline */
+  displayType?: 'row' | 'column' | 'inline';
+  /** 整个表单只读，所有字段以文本展示 */
+  readOnly?: boolean;
+  /** 表单每行显示多少列 */
+  column?: number;
+}
+
+function noop() {}
+
+/**
+ * NexusForm — 顶层表单组件
+ */
+export function NexusForm({
+  form,
+  schema,
+  initialValues,
+  widgets,
+  layouts,
+  onFinish,
+  onFinishFailed,
+  footer = false,
+  className,
+  style,
+  children,
+  labelCol,
+  labelWidth,
+  colon,
+  label,
+  displayType,
+  readOnly,
+  column,
+  watch,
+  removeHiddenData = true,
+}: NexusFormProps) {
+  const engine = form._getEngine();
+  const formElRef = useRef<HTMLFormElement | null>(null);
+
+  // Schema 顶层配置作为默认值，props 优先级更高
+  const finalDisplayType = displayType ?? schema?.displayType ?? 'row';
+  const finalLabel = label ?? schema?.label ?? true;
+  const finalColon = colon ?? schema?.colon;
+  const finalLabelWidth = labelWidth ?? schema?.labelWidth;
+  const finalReadOnly = readOnly ?? schema?.readOnly ?? false;
+  const finalColumn = column ?? schema?.column;
+
+  // 注册额外 widgets / layouts（仅首次或引用变化时）
+  useEffect(() => {
+    if (widgets) {
+      engine.registerWidgets(widgets);
+    }
+    if (layouts) {
+      engine.registerLayouts(layouts);
+    }
+  }, [engine, widgets, layouts]);
+
+  // schema 变化时重新初始化
+  // 注意：initialValues 仅在首次挂载时使用，避免每次渲染都 re-init 导致
+  // 已有的 errors / 用户输入被重置。后续需要更新值请使用 form.setValues()。
+  const isFirstInitRef = useRef(true);
+  const initialValuesRef = useRef(initialValues);
+  useEffect(() => {
+    if (!schema) {
+      return;
+    }
+    if (isFirstInitRef.current) {
+      engine.init(schema, initialValuesRef.current);
+      isFirstInitRef.current = false;
+    } else {
+      // schema 变化：保留当前已填数据，而非重置为 initialValues
+      engine.init(schema, engine.getFormData());
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [engine, schema]);
+
+  // 绑定 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;
+  onFinishFailedRef.current = onFinishFailed ?? noop;
+
+  // 只在挂载时绑定一次：传入「稳定的 getter」，让 FormController 在 submit 时读取最新回调
+  useEffect(() => {
+    form._bind(
+      formElRef.current,
+      () => onFinishRef.current,
+      () => onFinishFailedRef.current,
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [form]);
+
+  // watch / removeHiddenData 变化时单独同步（不重置其他绑定）
+  useEffect(() => {
+    form._syncConfig({ removeHiddenData, watch });
+  }, [form, removeHiddenData, watch]);
+
+  const _version = useSyncExternalStore(
+    engine.subscribeStore,
+    engine.getSnapshot,
+    engine.getSnapshot,
+  );
+  // 依赖 _version：engine.init() / setSchema() 会 bump version，
+  // 需要在此后重新读取 renderTree（首次渲染时 engine 尚未 init，renderTree 为空）
+  // biome-ignore lint/correctness/useExhaustiveDependencies: _version 是 renderTree 失效信号（engine 内部状态，静态分析不可见）
+  const renderTree = useMemo(() => engine.getRenderTree(), [engine, _version]);
+
+  const handleSubmit = useCallback(
+    async (e: SubmitEvent) => {
+      e.preventDefault();
+      await form.submit();
+    },
+    [form],
+  );
+
+  const handleReset = useCallback(() => {
+    form.resetFields();
+  }, [form]);
+
+  // footer 渲染
+  let footerNode: ReactNode = null;
+  if (footer === true) {
+    footerNode = (
+      <div className='mt-4'>
+        <button type='submit'>提交</button>{' '}
+        <button type='button' onClick={handleReset}>
+          重置
+        </button>
+      </div>
+    );
+  } else if (footer) {
+    footerNode = footer;
+  }
+
+  // labelCol: 合并 labelWidth 快捷方式
+  const mergedLabelCol = useMemo(() => {
+    if (labelCol) {
+      return labelCol;
+    }
+    if (finalLabelWidth) {
+      return {
+        style: {
+          width:
+            typeof finalLabelWidth === 'number'
+              ? `${finalLabelWidth}px`
+              : finalLabelWidth,
+        },
+      };
+    }
+    return undefined;
+  }, [labelCol, finalLabelWidth]);
+
+  // NexusFormConfig 传递给 Context（由 ui 层消费，自行实现布局）
+  const formConfig = useMemo<NexusFormConfig>(
+    () => ({
+      labelCol: mergedLabelCol,
+      labelWidth: finalLabelWidth,
+      colon: finalColon,
+      label: finalLabel,
+      displayType: finalDisplayType,
+      readOnly: finalReadOnly,
+      column: finalColumn,
+    }),
+    [
+      mergedLabelCol,
+      finalLabelWidth,
+      finalColon,
+      finalLabel,
+      finalDisplayType,
+      finalReadOnly,
+      finalColumn,
+    ],
+  );
+
+  return (
+    <NexusFormProvider engine={engine} config={formConfig} form={form}>
+      <form
+        ref={formElRef}
+        onSubmit={handleSubmit}
+        className={className}
+        style={{
+          ...style,
+          // 当配置了 column 时，使用 CSS Grid 布局
+          ...(finalColumn && finalColumn > 1
+            ? {
+                display: 'grid',
+                gridTemplateColumns: `repeat(${finalColumn}, 1fr)`,
+                gap: '0 16px',
+              }
+            : {}),
+        }}
+        noValidate
+      >
+        {renderTree.map((node, index) => renderTreeNode(node, index))}
+        {!readOnly && footerNode}
+        {children}
+      </form>
+    </NexusFormProvider>
+  );
+}

package/src/components/NexusFormProvider.tsx

@@ -0,0 +1,28 @@
+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';
+
+interface NexusFormProviderProps {
+  engine: NexusEngine;
+  config: NexusFormConfig;
+  form: FormController;
+  children: ReactNode;
+}
+
+export function NexusFormProvider({
+  engine,
+  config,
+  form,
+  children,
+}: NexusFormProviderProps) {
+  const value = useMemo(
+    () => ({ engine, config, form }),
+    [engine, config, form],
+  );
+  return (
+    <NexusContext.Provider value={value}>{children}</NexusContext.Provider>
+  );
+}

package/src/components/NexusLayout.tsx

@@ -0,0 +1,81 @@
+import type { RenderLayoutNode } from '@xbeeant/form-engine';
+import type { CSSProperties } from 'react';
+import { useContext, useMemo } from 'react';
+
+import { GridContext } from '../contexts/GridContext';
+import {
+  LayoutConfigContext,
+  type LayoutConfigContextValue,
+} from '../contexts/LayoutConfigContext';
+import { useNexusContext } from '../contexts/NexusContext';
+import { renderTreeNode } from '../utils/renderTreeNode';
+import { resolveColSpan } from '../utils/resolveColSpan';
+
+interface NexusLayoutProps {
+  node: RenderLayoutNode;
+}
+
+/**
+ * NexusLayout — 布局容器渲染器
+ */
+export function NexusLayout({ node }: NexusLayoutProps) {
+  const { engine } = useNexusContext();
+
+  const LayoutComponent = engine.getLayout(node.type);
+
+  const children = node.children.map((child, index) =>
+    renderTreeNode(child, index),
+  );
+
+  // 布局容器在父 Grid/Flex 中的跨列/宽度（与 NexusField wrapper 一致）
+  const gridCtx = useContext(GridContext);
+  const effectiveColSpan = resolveColSpan(node.props.colSpan, gridCtx);
+  const wrapperStyle: CSSProperties = {
+    ...(effectiveColSpan ? { gridColumn: `span ${effectiveColSpan}` } : {}),
+    ...(node.props.width ? { width: node.props.width, flexShrink: 0 } : {}),
+  };
+
+  const layoutConfigValue = useMemo<LayoutConfigContextValue>(
+    () => ({ removeHidden: node.props.removeHidden }),
+    [node.props.removeHidden],
+  );
+
+  if (!LayoutComponent) {
+    return (
+      <LayoutConfigContext.Provider value={layoutConfigValue}>
+        <div
+          data-nexus-layout={node.type}
+          className='mb-4'
+          style={
+            Object.keys(wrapperStyle).length > 0 ? wrapperStyle : undefined
+          }
+        >
+          {node.title && <div className='mb-2 font-bold'>{node.title}</div>}
+          {children}
+        </div>
+      </LayoutConfigContext.Provider>
+    );
+  }
+
+  // 剥离布局配置属性（displayType / labelWidth / colSpan / width 是布局配置，
+  // 不应透传到布局组件的 DOM 元素，否则触发 React unknown prop 警告）
+  const {
+    displayType: _dt,
+    labelWidth: _lw,
+    colSpan: _csp,
+    width: _w,
+    ...layoutProps
+  } = node.props;
+
+  return (
+    <LayoutConfigContext.Provider value={layoutConfigValue}>
+      <div
+        style={Object.keys(wrapperStyle).length > 0 ? wrapperStyle : undefined}
+      >
+        <LayoutComponent {...layoutProps} node={node} title={node.title}>
+          {children}
+        </LayoutComponent>
+      </div>
+    </LayoutConfigContext.Provider>
+  );
+}

package/src/components/NexusObject.tsx

@@ -0,0 +1,93 @@
+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';
+
+interface NexusObjectProps {
+  node: RenderObjectNode;
+}
+
+/**
+ * NexusObject — 数据对象容器（可折叠，支持 disabled/hidden/readOnly 属性配置）
+ *
+ * 点击 title 折叠/展开 children。
+ * 折叠时仅以 display:none 隐藏 children，并不销毁（字段状态与订阅保持存活）。
+ *
+ * 属性继承：容器自身（Schema 布尔值 / 表达式 / setFieldState）配置的
+ * disabled / readOnly / hidden 会经 FieldInheritContext 下发给子树，
+ * 子树中的字段继承对应状态（disabled/readOnly 仅父级激活时生效）。
+ */
+export function NexusObject({ node }: NexusObjectProps) {
+  const { engine, config } = useNexusContext();
+  const parentInherit = useContext(FieldInheritContext);
+  // 按路径精准订阅：自身 disabled/readOnly/visible 变化时重渲染并下发新上下文
+  useSyncExternalStore(
+    (onStoreChange) => engine.subscribeField(node.dataPath, onStoreChange),
+    () => engine.getFieldVersion(node.dataPath),
+    () => engine.getFieldVersion(node.dataPath),
+  );
+  const state = engine.getFieldState(node.dataPath);
+  const [collapsed, setCollapsed] = useState(false);
+  const isGrid = (config.column ?? 1) > 1;
+  const gridStyle: CSSProperties = isGrid
+    ? { gridTemplateColumns: `repeat(${config.column}, 1fr)` }
+    : {};
+
+  // 合并继承属性：父级已激活的状态不可被当前容器覆盖；
+  // disabled/readOnly 仅携带 true（父级关闭状态不压制子级显式启用）
+  const inherit = {
+    disabled:
+      parentInherit.disabled ?? (state?.disabled === true ? true : undefined),
+    readOnly:
+      parentInherit.readOnly ?? (state?.readOnly === true ? true : undefined),
+    visible:
+      parentInherit.visible === false || state?.visible === false
+        ? false
+        : undefined,
+  };
+  const hidden = inherit.visible === false;
+
+  const toggleCollapsed = () => setCollapsed((prev) => !prev);
+
+  return (
+    <FieldInheritContext.Provider value={inherit}>
+      <div
+        data-nexus-object={node.dataPath}
+        className={`mb-4 ${hidden ? 'hidden' : ''}`}
+      >
+        {node.title && (
+          <div
+            onClick={toggleCollapsed}
+            className='flex gap-1 mb-2 cursor-pointer select-none border-none bg-transparent p-0 font-bold'
+          >
+            <svg
+              width='12'
+              height='12'
+              viewBox='0 0 24 24'
+              fill='none'
+              stroke='currentColor'
+              strokeWidth='2'
+              strokeLinecap='round'
+              strokeLinejoin='round'
+              className={`align-middle transition-transform duration-200 ease-in-out ${collapsed ? 'rotate-0' : 'rotate-90'}`}
+              aria-hidden='true'
+            >
+              <polyline points='9 18 15 12 9 6' />
+            </svg>
+            {node.title}
+          </div>
+        )}
+        {/* 折叠时隐藏但不卸载 children，保持字段状态与校验订阅 */}
+        <div
+          className={`${isGrid ? 'grid gap-x-4' : ''} ${collapsed ? 'hidden' : ''}`}
+          style={Object.keys(gridStyle).length > 0 ? gridStyle : undefined}
+        >
+          {node.children.map((child, index) => renderTreeNode(child, index))}
+        </div>
+      </div>
+    </FieldInheritContext.Provider>
+  );
+}

package/src/contexts/FieldInheritContext.ts

@@ -0,0 +1,21 @@
+import { createContext } from 'react';
+
+/**
+ * 字段继承上下文 — 数据对象容器（NexusObject）向下游字段下发继承属性
+ *
+ * 语义：
+ * - 仅「激活」状态被下发：disabled/readOnly 只在父容器显式启用时
+ *   携带 true（父级未设置时上下文不存在该键），子字段自行合并
+ * - visible 为 false 表示祖先对象容器隐藏，子树整体不可见
+ * - 合并优先级：祖先（已激活） > 字段自身状态 > 默认值
+ */
+export interface FieldInheritValue {
+  /** 祖先对象容器禁用（仅 true 存在） */
+  disabled?: boolean;
+  /** 祖先对象容器只读（仅 true 存在） */
+  readOnly?: boolean;
+  /** 祖先对象容器隐藏 → 子树不可见（false 存在时子树全部隐藏） */
+  visible?: boolean;
+}
+
+export const FieldInheritContext = createContext<FieldInheritValue>({});

package/src/contexts/GridContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+
+// 子项未显式设置 colSpan 时使用此默认值
+export interface GridContextValue {
+  /** 当前 grid 的列数（tailwind colSpan 基准） */
+  column: number;
+}
+export const GridContext = createContext<GridContextValue | null>(null);

package/src/contexts/LayoutConfigContext.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+export interface LayoutConfigContextValue {
+  removeHidden?: boolean;
+}
+export const LayoutConfigContext = createContext<LayoutConfigContextValue>({});

package/src/contexts/NexusContext.ts

@@ -0,0 +1,41 @@
+import type { NexusEngine } from '@xbeeant/form-engine';
+import { createContext, type ReactNode, useContext } from 'react';
+
+import type { FormController } from '../components/FormController';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Form 布局配置
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface NexusFormConfig {
+  /** label 列配置（由 ui 层 Form.Item 消费） */
+  labelCol?: Record<string, unknown>;
+  /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
+  labelWidth?: number | string;
+  /** 是否显示冒号 */
+  colon?: boolean | ReactNode;
+  /** 是否显示 label（默认 true） */
+  label?: boolean;
+  /** 表单布局方向 */
+  displayType?: 'row' | 'column' | 'inline';
+  /** 整个表单只读，所有字段以文本展示 */
+  readOnly?: boolean;
+  /** 表单每行显示多少列 */
+  column?: number;
+}
+
+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/index.ts

@@ -0,0 +1,11 @@
+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';

package/src/hooks/useEngine.ts

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

package/src/hooks/useFieldState.ts

@@ -0,0 +1,21 @@
+import type { FieldState } from '@xbeeant/form-engine';
+import { useSyncExternalStore } from 'react';
+
+import { useNexusContext } from '../contexts/NexusContext';
+
+/**
+ * useFieldState — 精准订阅单个字段状态
+ *
+ * 按路径精准订阅：只在该字段版本变化时触发重渲染，避免全局订阅拖垮表单
+ */
+export function useFieldState(path: string): FieldState | undefined {
+  const { engine } = useNexusContext();
+
+  useSyncExternalStore(
+    (onStoreChange) => engine.subscribeField(path, onStoreChange),
+    () => engine.getFieldVersion(path),
+    () => engine.getFieldVersion(path),
+  );
+
+  return engine.getFieldState(path);
+}