@xbeeant/form-engine-react 0.0.1

package/dist/es/components/NexusForm.js

@@ -0,0 +1,120 @@
+import { jsx as b, jsxs as L } from "react/jsx-runtime";
+import { useRef as l, useEffect as o, useSyncExternalStore as Q, useMemo as y, useCallback as W } from "react";
+import { renderTreeNode as U } from "../utils/renderTreeNode.js";
+import { NexusFormProvider as X } from "./NexusFormProvider.js";
+function s() {
+}
+function ne({
+  form: n,
+  schema: t,
+  initialValues: _,
+  widgets: u,
+  layouts: c,
+  onFinish: j,
+  onFinishFailed: k,
+  footer: a = !1,
+  className: D,
+  style: O,
+  children: V,
+  labelCol: f,
+  labelWidth: $,
+  colon: I,
+  label: M,
+  displayType: P,
+  readOnly: g,
+  column: q,
+  watch: m,
+  removeHiddenData: R = !0
+}) {
+  const e = n._getEngine(), x = l(null), F = P ?? t?.displayType ?? "row", C = M ?? t?.label ?? !0, S = I ?? t?.colon, r = $ ?? t?.labelWidth, T = g ?? t?.readOnly ?? !1, i = q ?? t?.column;
+  o(() => {
+    u && e.registerWidgets(u), c && e.registerLayouts(c);
+  }, [e, u, c]);
+  const h = l(!0), w = l(_);
+  o(() => {
+    t && (h.current ? (e.init(t, w.current), h.current = !1) : e.init(t, e.getFormData()));
+  }, [e, t]);
+  const N = l(s), v = l(s);
+  N.current = j ?? s, v.current = k ?? s, o(() => {
+    n._bind(
+      x.current,
+      () => N.current,
+      () => v.current
+    );
+  }, [n]), o(() => {
+    n._syncConfig({ removeHiddenData: R, watch: m });
+  }, [n, R, m]);
+  const z = Q(
+    e.subscribeStore,
+    e.getSnapshot,
+    e.getSnapshot
+  ), A = y(() => e.getRenderTree(), [e, z]), B = W(
+    async (p) => {
+      p.preventDefault(), await n.submit();
+    },
+    [n]
+  ), G = W(() => {
+    n.resetFields();
+  }, [n]);
+  let d = null;
+  a === !0 ? d = /* @__PURE__ */ L("div", { className: "mt-4", children: [
+    /* @__PURE__ */ b("button", { type: "submit", children: "提交" }),
+    " ",
+    /* @__PURE__ */ b("button", { type: "button", onClick: G, children: "重置" })
+  ] }) : a && (d = a);
+  const E = y(() => {
+    if (f)
+      return f;
+    if (r)
+      return {
+        style: {
+          width: typeof r == "number" ? `${r}px` : r
+        }
+      };
+  }, [f, r]), J = y(
+    () => ({
+      labelCol: E,
+      labelWidth: r,
+      colon: S,
+      label: C,
+      displayType: F,
+      readOnly: T,
+      column: i
+    }),
+    [
+      E,
+      r,
+      S,
+      C,
+      F,
+      T,
+      i
+    ]
+  );
+  return /* @__PURE__ */ b(X, { engine: e, config: J, form: n, children: /* @__PURE__ */ L(
+    "form",
+    {
+      ref: x,
+      onSubmit: B,
+      className: D,
+      style: {
+        ...O,
+        // 当配置了 column 时，使用 CSS Grid 布局
+        ...i && i > 1 ? {
+          display: "grid",
+          gridTemplateColumns: `repeat(${i}, 1fr)`,
+          gap: "0 16px"
+        } : {}
+      },
+      noValidate: !0,
+      children: [
+        A.map((p, K) => U(p, K)),
+        !g && d,
+        V
+      ]
+    }
+  ) });
+}
+export {
+  ne as NexusForm
+};

package/dist/es/components/NexusFormProvider.d.ts

@@ -0,0 +1,12 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+import { ReactNode } from 'react';
+import { FormController } from './FormController';
+import { NexusFormConfig } from './NexusForm';
+interface NexusFormProviderProps {
+    engine: NexusEngine;
+    config: NexusFormConfig;
+    form: FormController;
+    children: ReactNode;
+}
+export declare function NexusFormProvider({ engine, config, form, children, }: NexusFormProviderProps): import("react").JSX.Element;
+export {};

package/dist/es/components/NexusFormProvider.js

@@ -0,0 +1,18 @@
+import { jsx as u } from "react/jsx-runtime";
+import { useMemo as s } from "react";
+import { NexusContext as x } from "../contexts/NexusContext.js";
+function d({
+  engine: r,
+  config: o,
+  form: t,
+  children: e
+}) {
+  const m = s(
+    () => ({ engine: r, config: o, form: t }),
+    [r, o, t]
+  );
+  return /* @__PURE__ */ u(x.Provider, { value: m, children: e });
+}
+export {
+  d as NexusFormProvider
+};

package/dist/es/components/NexusLayout.d.ts

@@ -0,0 +1,9 @@
+import { RenderLayoutNode } from '@xbeeant/form-engine';
+interface NexusLayoutProps {
+    node: RenderLayoutNode;
+}
+/**
+ * NexusLayout — 布局容器渲染器
+ */
+export declare function NexusLayout({ node }: NexusLayoutProps): import("react").JSX.Element;
+export {};

package/dist/es/components/NexusLayout.js

@@ -0,0 +1,48 @@
+import { jsx as e, jsxs as u } from "react/jsx-runtime";
+import { useContext as y, useMemo as f } from "react";
+import { GridContext as h } from "../contexts/GridContext.js";
+import { LayoutConfigContext as p } from "../contexts/LayoutConfigContext.js";
+import { useNexusContext as v } from "../contexts/NexusContext.js";
+import { renderTreeNode as x } from "../utils/renderTreeNode.js";
+import { resolveColSpan as C } from "../utils/resolveColSpan.js";
+function O({ node: t }) {
+  const { engine: n } = v(), r = n.getLayout(t.type), i = t.children.map(
+    (c, d) => x(c, d)
+  ), a = y(h), l = C(t.props.colSpan, a), o = {
+    ...l ? { gridColumn: `span ${l}` } : {},
+    ...t.props.width ? { width: t.props.width, flexShrink: 0 } : {}
+  }, s = f(
+    () => ({ removeHidden: t.props.removeHidden }),
+    [t.props.removeHidden]
+  );
+  if (!r)
+    return /* @__PURE__ */ e(p.Provider, { value: s, children: /* @__PURE__ */ u(
+      "div",
+      {
+        "data-nexus-layout": t.type,
+        className: "mb-4",
+        style: Object.keys(o).length > 0 ? o : void 0,
+        children: [
+          t.title && /* @__PURE__ */ e("div", { className: "mb-2 font-bold", children: t.title }),
+          i
+        ]
+      }
+    ) });
+  const {
+    displayType: g,
+    labelWidth: w,
+    colSpan: b,
+    width: S,
+    ...m
+  } = t.props;
+  return /* @__PURE__ */ e(p.Provider, { value: s, children: /* @__PURE__ */ e(
+    "div",
+    {
+      style: Object.keys(o).length > 0 ? o : void 0,
+      children: /* @__PURE__ */ e(r, { ...m, node: t, title: t.title, children: i })
+    }
+  ) });
+}
+export {
+  O as NexusLayout
+};

package/dist/es/components/NexusObject.d.ts

@@ -0,0 +1,16 @@
+import { RenderObjectNode } from '@xbeeant/form-engine';
+interface NexusObjectProps {
+    node: RenderObjectNode;
+}
+/**
+ * NexusObject — 数据对象容器（可折叠，支持 disabled/hidden/readOnly 属性配置）
+ *
+ * 点击 title 折叠/展开 children。
+ * 折叠时仅以 display:none 隐藏 children，并不销毁（字段状态与订阅保持存活）。
+ *
+ * 属性继承：容器自身（Schema 布尔值 / 表达式 / setFieldState）配置的
+ * disabled / readOnly / hidden 会经 FieldInheritContext 下发给子树，
+ * 子树中的字段继承对应状态（disabled/readOnly 仅父级激活时生效）。
+ */
+export declare function NexusObject({ node }: NexusObjectProps): import("react").JSX.Element;
+export {};

package/dist/es/components/NexusObject.js

@@ -0,0 +1,64 @@
+import { jsx as r, jsxs as u } from "react/jsx-runtime";
+import { useContext as g, useSyncExternalStore as v, useState as x } from "react";
+import { FieldInheritContext as h } from "../contexts/FieldInheritContext.js";
+import { useNexusContext as y } from "../contexts/NexusContext.js";
+import { renderTreeNode as C } from "../utils/renderTreeNode.js";
+function O({ node: e }) {
+  const { engine: i, config: a } = y(), s = g(h);
+  v(
+    (t) => i.subscribeField(e.dataPath, t),
+    () => i.getFieldVersion(e.dataPath),
+    () => i.getFieldVersion(e.dataPath)
+  );
+  const n = i.getFieldState(e.dataPath), [o, m] = x(!1), l = (a.column ?? 1) > 1, d = l ? { gridTemplateColumns: `repeat(${a.column}, 1fr)` } : {}, c = {
+    disabled: s.disabled ?? (n?.disabled === !0 ? !0 : void 0),
+    readOnly: s.readOnly ?? (n?.readOnly === !0 ? !0 : void 0),
+    visible: s.visible === !1 || n?.visible === !1 ? !1 : void 0
+  }, p = c.visible === !1, b = () => m((t) => !t);
+  return /* @__PURE__ */ r(h.Provider, { value: c, children: /* @__PURE__ */ u(
+    "div",
+    {
+      "data-nexus-object": e.dataPath,
+      className: `mb-4 ${p ? "hidden" : ""}`,
+      children: [
+        e.title && /* @__PURE__ */ u(
+          "div",
+          {
+            onClick: b,
+            className: "flex gap-1 mb-2 cursor-pointer select-none border-none bg-transparent p-0 font-bold",
+            children: [
+              /* @__PURE__ */ r(
+                "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 ${o ? "rotate-0" : "rotate-90"}`,
+                  "aria-hidden": "true",
+                  children: /* @__PURE__ */ r("polyline", { points: "9 18 15 12 9 6" })
+                }
+              ),
+              e.title
+            ]
+          }
+        ),
+        /* @__PURE__ */ r(
+          "div",
+          {
+            className: `${l ? "grid gap-x-4" : ""} ${o ? "hidden" : ""}`,
+            style: Object.keys(d).length > 0 ? d : void 0,
+            children: e.children.map((t, f) => C(t, f))
+          }
+        )
+      ]
+    }
+  ) });
+}
+export {
+  O as NexusObject
+};

package/dist/es/contexts/FieldInheritContext.d.ts

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

package/dist/es/contexts/FieldInheritContext.js

@@ -0,0 +1,5 @@
+import { createContext as t } from "react";
+const o = t({});
+export {
+  o as FieldInheritContext
+};

package/dist/es/contexts/GridContext.d.ts

@@ -0,0 +1,5 @@
+export interface GridContextValue {
+    /** 当前 grid 的列数（tailwind colSpan 基准） */
+    column: number;
+}
+export declare const GridContext: import('react').Context<GridContextValue | null>;

package/dist/es/contexts/GridContext.js

@@ -0,0 +1,5 @@
+import { createContext as t } from "react";
+const e = t(null);
+export {
+  e as GridContext
+};

package/dist/es/contexts/LayoutConfigContext.d.ts

@@ -0,0 +1,4 @@
+export interface LayoutConfigContextValue {
+    removeHidden?: boolean;
+}
+export declare const LayoutConfigContext: import('react').Context<LayoutConfigContextValue>;

package/dist/es/contexts/LayoutConfigContext.js

@@ -0,0 +1,5 @@
+import { createContext as t } from "react";
+const e = t({});
+export {
+  e as LayoutConfigContext
+};

package/dist/es/contexts/NexusContext.d.ts

@@ -0,0 +1,27 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+import { ReactNode } from 'react';
+import { FormController } from '../components/FormController';
+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 declare const NexusContext: import('react').Context<NexusContextValue | null>;
+export declare function useNexusContext(): NexusContextValue;
+export {};

package/dist/es/contexts/NexusContext.js

@@ -0,0 +1,12 @@
+import { createContext as t, useContext as o } from "react";
+const r = t(null);
+function u() {
+  const e = o(r);
+  if (!e)
+    throw new Error("[NexusField] Must be used within <NexusFormProvider>");
+  return e;
+}
+export {
+  r as NexusContext,
+  u as useNexusContext
+};

package/dist/es/hooks/index.d.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/dist/es/hooks/index.js

@@ -0,0 +1,24 @@
+import { useEngine as r } from "./useEngine.js";
+import { useFieldState as m } from "./useFieldState.js";
+import { useFieldValidator as f } from "./useFieldValidator.js";
+import { useFieldValue as a } from "./useFieldValue.js";
+import { useForm as x } from "./useForm.js";
+import { useFormConfig as i } from "./useFormConfig.js";
+import { useFormData as c } from "./useFormData.js";
+import { useWatch as h } from "./useWatch.js";
+import { useWatchAll as n } from "./useWatchAll.js";
+import { useWatchMultiple as S } from "./useWatchMultiple.js";
+import { useWatchState as A } from "./useWatchState.js";
+export {
+  r as useEngine,
+  m as useFieldState,
+  f as useFieldValidator,
+  a as useFieldValue,
+  x as useForm,
+  i as useFormConfig,
+  c as useFormData,
+  h as useWatch,
+  n as useWatchAll,
+  S as useWatchMultiple,
+  A as useWatchState
+};

package/dist/es/hooks/useEngine.d.ts

@@ -0,0 +1,2 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+export declare function useEngine(): NexusEngine;

package/dist/es/hooks/useEngine.js

@@ -0,0 +1,8 @@
+import { useNexusContext as n } from "../contexts/NexusContext.js";
+function o() {
+  const { engine: e } = n();
+  return e;
+}
+export {
+  o as useEngine
+};

package/dist/es/hooks/useFieldState.d.ts

@@ -0,0 +1,7 @@
+import { FieldState } from '@xbeeant/form-engine';
+/**
+ * useFieldState — 精准订阅单个字段状态
+ *
+ * 按路径精准订阅：只在该字段版本变化时触发重渲染，避免全局订阅拖垮表单
+ */
+export declare function useFieldState(path: string): FieldState | undefined;

package/dist/es/hooks/useFieldState.js

@@ -0,0 +1,13 @@
+import { useSyncExternalStore as r } from "react";
+import { useNexusContext as n } from "../contexts/NexusContext.js";
+function u(e) {
+  const { engine: t } = n();
+  return r(
+    (i) => t.subscribeField(e, i),
+    () => t.getFieldVersion(e),
+    () => t.getFieldVersion(e)
+  ), t.getFieldState(e);
+}
+export {
+  u as useFieldState
+};

package/dist/es/hooks/useFieldValidator.d.ts

@@ -0,0 +1,40 @@
+import { NexusFormInstance } from '@xbeeant/form-engine';
+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 declare function useFieldValidator(form: NexusFormInstance | undefined, path: string | undefined, validator: FieldValidator, options?: UseFieldValidatorOptions): void;

package/dist/es/hooks/useFieldValidator.js

@@ -0,0 +1,35 @@
+import { useRef as o, useEffect as f } from "react";
+import { useNexusContext as b } from "../contexts/NexusContext.js";
+function R(r, e, c, s) {
+  const { engine: i } = b(), d = o(c);
+  d.current = c;
+  const t = o(s?.dependsOn);
+  t.current = s?.dependsOn;
+  const l = s?.deps;
+  f(() => {
+    if (!r || !e)
+      return;
+    const n = d.current;
+    return r.registerValidator(e, n), () => {
+      r.unregisterValidator(e, n);
+    };
+  }, [r, e, ...l ?? []]), f(() => {
+    if (!e || !t.current || t.current.length === 0)
+      return;
+    const n = i;
+    if (!n)
+      return;
+    const g = e, a = t.current.map(
+      (u) => n.subscribeField(u, () => {
+        r?.revalidateField(g);
+      })
+    );
+    return () => {
+      for (const u of a)
+        u();
+    };
+  }, [i, r, e]);
+}
+export {
+  R as useFieldValidator
+};

package/dist/es/hooks/useFieldValue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useFieldValue — 精准订阅单个字段值
+ *
+ * 按路径精准订阅：仅该字段版本变化时重渲染
+ */
+export declare function useFieldValue<T = unknown>(path: string): T | undefined;

package/dist/es/hooks/useFieldValue.js

@@ -0,0 +1,13 @@
+import { useSyncExternalStore as r } from "react";
+import { useEngine as o } from "./useEngine.js";
+function t(e) {
+  const i = o();
+  return r(
+    (n) => i.subscribeField(e, n),
+    () => i.getFieldVersion(e),
+    () => i.getFieldVersion(e)
+  ), i.getFieldValue(e);
+}
+export {
+  t as useFieldValue
+};

package/dist/es/hooks/useForm.d.ts

@@ -0,0 +1,6 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+import { FormController } from '../components/FormController';
+/**
+ * useForm — 创建 Form 实例
+ */
+export declare function useForm(engine?: NexusEngine): [FormController];

package/dist/es/hooks/useForm.js

@@ -0,0 +1,9 @@
+import { useRef as e } from "react";
+import { FormController as n } from "../components/FormController.js";
+function f(o) {
+  const r = e(null);
+  return r.current || (r.current = new n(o)), [r.current];
+}
+export {
+  f as useForm
+};

package/dist/es/hooks/useFormConfig.d.ts

@@ -0,0 +1,5 @@
+import { NexusFormConfig } from '../components/NexusForm';
+/**
+ * useFormConfig — 获取表单布局配置
+ */
+export declare function useFormConfig(): NexusFormConfig;

package/dist/es/hooks/useFormConfig.js

@@ -0,0 +1,8 @@
+import { useNexusContext as n } from "../contexts/NexusContext.js";
+function e() {
+  const { config: o } = n();
+  return o;
+}
+export {
+  e as useFormConfig
+};

package/dist/es/hooks/useFormData.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useFormData — 订阅整个表单数据
+ *
+ * 用 version 作为快照依赖，避免 getFormData() 每次返回新对象引用导致的无谓重渲染
+ */
+export declare function useFormData(): Record<string, unknown>;

package/dist/es/hooks/useFormData.js

@@ -0,0 +1,13 @@
+import { useSyncExternalStore as o, useMemo as n } from "react";
+import { useEngine as r } from "./useEngine.js";
+function i() {
+  const e = r(), t = o(
+    e.subscribeStore,
+    e.getSnapshot,
+    e.getSnapshot
+  );
+  return n(() => e.getFormData(), [e, t]);
+}
+export {
+  i as useFormData
+};

package/dist/es/hooks/useNexusContext.d.ts

@@ -0,0 +1,11 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+import { FormController } from '../components/FormController';
+import { NexusFormConfig } from '../components/NexusForm';
+interface NexusContextValue {
+    engine: NexusEngine;
+    config: NexusFormConfig;
+    form: FormController;
+}
+export declare const NexusContext: import('react').Context<NexusContextValue | null>;
+export declare function useNexusContext(): NexusContextValue;
+export {};

package/dist/es/hooks/useNexusContext.js

@@ -0,0 +1,12 @@
+import { createContext as t, useContext as o } from "react";
+const r = t(null);
+function u() {
+  const e = o(r);
+  if (!e)
+    throw new Error("[NexusField] Must be used within <NexusFormProvider>");
+  return e;
+}
+export {
+  r as NexusContext,
+  u as useNexusContext
+};