@para-ui/core 5.0.1 → 5.0.3-beta.8

package/es/FieldForm/Form.js

@@ -1,92 +1,96 @@
 import { j as i } from "../_virtual/jsx-runtime.js";
-import { forwardRef as P, useState as S, useContext as T, useMemo as F, useRef as q, useImperativeHandle as w, useEffect as z } from "react";
-import V from "../_virtual/index.js";
-import G from "rc-field-form";
-import { useWatch as ie } from "rc-field-form";
-import { $prefixCls as H } from "../GlobalContext/constant.js";
-import k from "./hooks/useForm.js";
-import { FormProvider as B, FormContext as D } from "./context.js";
-import { defaultValidateMessages as J } from "./lang/index.js";
-import K from "../GlobalContext/index.js";
-const n = `${H}-field-form`, O = (b, W) => {
+import { forwardRef as T, useState as q, useContext as w, useMemo as W, useRef as z, useImperativeHandle as V, useEffect as D } from "react";
+import G from "../_virtual/index.js";
+import H from "rc-field-form";
+import { useWatch as me } from "rc-field-form";
+import { $prefixCls as k } from "../GlobalContext/constant.js";
+import B from "./hooks/useForm.js";
+import { FormProvider as J, FormContext as K } from "./context.js";
+import { defaultValidateMessages as O } from "./lang/index.js";
+import Q from "../GlobalContext/index.js";
+const n = `${k}-field-form`, U = (v, E) => {
   const {
-    className: v,
+    className: R,
     disabled: m,
-    form: E,
+    form: g,
     colon: c,
     labelAlign: f,
     labelWidth: r,
-    labelWrap: R,
+    labelWrap: M,
     layout: d = "vertical",
-    onFinishFailed: M,
+    onFinishFailed: C,
     name: t,
-    style: g,
+    style: L,
     size: u,
-    ...C
-  } = b, [l, L] = S(0), { language: p } = T(K), j = F(
-    () => J[p || "zh"],
-    [p]
-  ), [o] = k(E), { __INTERNAL__: x } = o;
-  x.name = t;
-  const a = q(null);
-  w(W, () => ({
+    spacing: p = "normal",
+    itemDecorator: x,
+    ...j
+  } = v, [l, y] = q(0), { language: h } = w(Q), I = W(
+    () => O[h || "zh"],
+    [h]
+  ), [o] = B(g), { __INTERNAL__: F } = o;
+  F.name = t;
+  const a = z(null);
+  V(E, () => ({
     ...o,
     nativeElement: a.current?.nativeElement
   }));
-  const y = (e) => {
-    M?.(e);
-  }, I = (e) => {
+  const N = (e) => {
+    C?.(e);
+  }, _ = (e) => {
     if (!e) return;
-    const _ = e.querySelectorAll(`.${n}-item`);
+    const A = e.querySelectorAll(`.${n}-item`);
     let s = 0;
-    _?.forEach(($) => {
-      const h = $.querySelector("label");
-      if (h) {
-        const A = h.offsetWidth;
-        s = Math.max(s, A);
+    A?.forEach((P) => {
+      const b = P.querySelector("label");
+      if (b) {
+        const S = b.offsetWidth;
+        s = Math.max(s, S);
       }
-    }), L(s);
+    }), y(s);
   };
-  z(() => {
+  D(() => {
     const e = setTimeout(() => {
-      I(a.current?.nativeElement);
+      _(a.current?.nativeElement);
     }, 0);
     return () => clearTimeout(e);
   }, []);
-  const N = F(
+  const $ = W(
     () => ({
       name: t,
       labelAlign: f,
-      labelWrap: r ? R : !1,
+      labelWrap: r ? M : !1,
       labelWidth: r || l,
       labelMaxWidth: l,
       layout: d,
       colon: c,
-      itemRef: x.itemRef,
+      itemRef: F.itemRef,
       form: o,
       prefixCls: n,
       disabled: m,
-      size: u
+      size: u,
+      spacing: p,
+      itemDecorator: x
     }),
-    [t, f, d, c, o, m, l, r, u]
+    [t, f, d, c, o, m, l, r, u, p, x]
   );
-  return /* @__PURE__ */ i.jsx(B, { validateMessages: j, children: /* @__PURE__ */ i.jsx(D.Provider, { value: N, children: /* @__PURE__ */ i.jsx(
-    G,
+  return /* @__PURE__ */ i.jsx(J, { validateMessages: I, children: /* @__PURE__ */ i.jsx(K.Provider, { value: $, children: /* @__PURE__ */ i.jsx(
+    H,
     {
       id: t,
-      ...C,
+      ...j,
       name: t,
-      onFinishFailed: y,
+      onFinishFailed: N,
       form: o,
       ref: a,
-      className: V(v, n),
-      style: { ...g }
+      className: G(R, n),
+      style: { ...L }
     }
   ) }) });
-}, le = P(O);
+}, se = T(U);
 export {
-  le as default,
-  k as useForm,
-  ie as useWatch
+  se as default,
+  B as useForm,
+  me as useWatch
 };
 //# sourceMappingURL=Form.js.map

package/es/FieldForm/compactControlMarker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @description Switch/Checkbox 类矮控件的 compact 间距自动识别标记约定。
+ *
+ * `FieldForm.Item` 在未显式指定 `spacing` 时，会检查唯一直接子节点是否为矮控件，
+ * 自动落 compact 档（见 `util.ts` 的 `isCompactControlChild`）。原生 `Switch`/`Checkbox`
+ * 靠类型引用直接比对即可命中；但消费方常见做法是自己再包一层组件（如加 label 布局），
+ * 包完之后子节点的类型引用就不再等于 `@para-ui/core` 原生组件，直接比对会失效。
+ *
+ * 为此原生 `Switch`/`Checkbox` 会在自身函数上挂这个标记，消费方若对它们做二次封装，
+ * 只需把标记原样透传到自己的包装组件上（`WrapperComponent[PARA_UI_COMPACT_CONTROL_MARKER] = true`），
+ * 包装组件即可继续被识别为矮控件——不需要 `@para-ui/core` 反过来认识具体消费方的包装组件。
+ *
+ * 独立成文件是为了避免循环依赖：这个标记同时被 `Switch`/`Checkbox`（声明"我是矮控件"）
+ * 和 `FieldForm/util.ts`（读取标记做判断，同时也直接引用 Switch/Checkbox 做引用相等比对）
+ * 引用，若把标记定义放进 `FieldForm/util.ts` 会形成 `Switch → FieldForm/util.ts → Switch`
+ * 的循环引用。
+ */
+export declare const PARA_UI_COMPACT_CONTROL_MARKER = "__paraUiCompactControl__";

package/es/FieldForm/compactControlMarker.js

@@ -0,0 +1,5 @@
+const _ = "__paraUiCompactControl__";
+export {
+  _ as PARA_UI_COMPACT_CONTROL_MARKER
+};
+//# sourceMappingURL=compactControlMarker.js.map

package/es/FieldForm/component.json

@@ -61,6 +61,20 @@
         "children": {
             "type": "ReactNode",
             "description": "FieldForm 接收任意 ReactNode(包括 FieldForm.Item / Button type=submit / 自定义包装);**但每个 Item 的 child 必须是支持 value/onChange/error/disabled 的自定义组件**(TextField / Select / Checkbox / Switch / DatePicker / InputNumber 等);**不可用原生 input/textarea/select/button — 会触发 React non-boolean-attribute warning**(因 cloneElement 注入 error={false} 给原生 DOM 元素时,React 视 error 为 DOM attr → 报错);见 childrenContract.FormItem"
+        },
+        "itemDecorator": {
+            "type": "ItemDecorator",
+            "objectShape": {
+                "getItemClassName": {
+                    "type": "(meta: ItemDecoratorMeta) => string | undefined | false",
+                    "description": "按字段 namePath/path 返回要合并到该 FieldForm.Item 根节点的 className;返回 undefined/''/false 时不追加，不影响其他状态 class(is-error/is-success 等)"
+                },
+                "renderItemExtra": {
+                    "type": "(meta: ItemDecoratorMeta) => ReactNode",
+                    "description": "按字段 namePath/path 在该 FieldForm.Item 根节点内追加渲染内容(如 diff 命中原因说明);渲染在根节点内、内部间距容器之外，不影响 has-spacing/has-helper-text 的 20px 间距机制"
+                }
+            },
+            "description": "Form 级一次注册、所有子孙 FieldForm.Item 自动生效的字段装饰扩展点;meta.namePath 来自 rc-field-form 的 renderMeta.name(真实的、经过 List 等上下文处理后的最终路径)，meta.path 是预拼接字符串(数组下标用方括号,如 'ubr.list[0].x');未传 name 的 Item 固定拿到 { namePath: [], path: '' };典型用法:`<FieldForm itemDecorator={{ getItemClassName: (meta) => isHit(meta.path) ? 'is-hit' : undefined, renderItemExtra: (meta) => isHit(meta.path) ? <span>命中原因</span> : null }}>`"
         }
     },
     "childrenContract": {
@@ -137,7 +151,9 @@
         "把'仅使用 FieldForm 本身'解读为'整个文件不能 import TextField/Button'(见 interpretivePriority.resolution)",
         "字段过多不分组",
         "忽略异步校验",
-        "在 mount 后修改 initialValues prop(应用 form.setFieldsValue;initialValues 仅 mount 时灌入)"
+        "在 mount 后修改 initialValues prop(应用 form.setFieldsValue;initialValues 仅 mount 时灌入)",
+        "在 itemDecorator.getItemClassName/renderItemExtra 回调体内调用 useContext/useXxx 等 Hook(回调运行在 ItemHolder 渲染过程中，不在业务组件自身的渲染调用栈里，会违反 Hooks 规则;应在业务组件顶层用 Hook 取数后，用 useMemo 包成闭包再传入 itemDecorator)",
+        "期望 itemDecorator 对 noStyle 的 FieldForm.Item 生效(noStyle 不渲染独立 wrapper 节点，没有可挂载 className/额外内容的位置)"
     ],
     "events": {
         "onFinish": {
@@ -187,6 +203,11 @@
             "issue": "rules 中的 validator 函数签名必须返回 Promise(rc-field-form 约定),不是同步返回",
             "wrong": "rules={[{ validator: (_, val) => val > 0 ? true : false }]}  // 同步返回 boolean 不被识别",
             "right": "rules={[{ validator: (_, val) => val > 0 ? Promise.resolve() : Promise.reject('必须大于 0') }]}"
+        },
+        {
+            "issue": "itemDecorator 的 getItemClassName/renderItemExtra 回调不能在函数体内调用 React Hook",
+            "wrong": "itemDecorator={{ getItemClassName: (meta) => { const hit = useFieldHighlight(meta.path); return hit ? 'is-hit' : undefined; } }}  // 在回调体内调用 Hook，违反 Hooks 规则",
+            "right": "const highlightMap = useFieldHighlightMap();\nconst itemDecorator = useMemo(() => ({ getItemClassName: (meta) => (highlightMap[meta.path] ? 'is-hit' : undefined) }), [highlightMap]);\n<FieldForm itemDecorator={itemDecorator}>"
         }
     ],
     "mapping": {

package/es/FieldForm/context.d.ts

@@ -1,7 +1,7 @@
 import { default as React, FC, ReactElement, Key, ReactNode } from 'react';
 import { FormProviderProps as RcFormProviderProps } from 'rc-field-form/lib/FormContext';
 import { Meta } from 'rc-field-form/lib/interface';
-import { FormLabelAlign } from './interface';
+import { FormLabelAlign, ItemDecorator } from './interface';
 import { FormInstance, FormLayout } from './Form';
 import { ValidateStatus } from './FieldFormItem';
 export declare const FormProvider: FC<RcFormProviderProps>;
@@ -18,6 +18,8 @@ export interface FormContextProps {
     prefixCls?: string;
     disabled?: boolean;
     size?: 'small' | 'medium' | 'large';
+    spacing: 'normal' | 'compact';
+    itemDecorator?: ItemDecorator;
 }
 export declare const FormContext: React.Context<FormContextProps>;
 /** rc-field-form 在销毁字段时会传入带 destroy 标记的 meta(官方 Meta 类型未声明此字段) */

package/es/FieldForm/context.js

@@ -5,16 +5,17 @@ import i from "rc-util/lib/omit";
 const x = (t) => {
   const r = i(t, ["prefixCls"]);
   return /* @__PURE__ */ e.jsx(m, { ...r });
-}, c = o({
+}, a = o({
   labelAlign: "left",
   layout: "vertical",
+  spacing: "normal",
   itemRef: () => () => {
   }
-}), f = o(null), a = o({});
+}), c = o(null), f = o({});
 export {
-  c as FormContext,
-  a as FormItemInputContext,
+  a as FormContext,
+  f as FormItemInputContext,
   x as FormProvider,
-  f as NoStyleItemContext
+  c as NoStyleItemContext
 };
 //# sourceMappingURL=context.js.map

package/es/FieldForm/index.css

@@ -1 +1 @@
-@charset "UTF-8";.paraui-v4-field-form-item{vertical-align:top}.paraui-v4-field-form-item.is-horizontal{display:flex}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label{margin-right:8px;padding:0;flex-shrink:0;text-align:end}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-left{text-align:start}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-multiline .paraui-v4-field-form-label-comp{display:inline-block}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label-comp{width:100%;display:inline-flex;align-items:center;margin:0;max-width:100%;min-height:32px}.paraui-v4-field-form-content{flex:1}.paraui-v4-field-form-content.has-spacing{margin-bottom:20px}.paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-control-input{display:flex;align-items:center;min-height:32px}.paraui-v4-field-form-control-input-content{width:100%}.paraui-v4-field-form-control-input-content .paraui-v4-radio-group>.radio-group-content .radio-item-box{margin-bottom:0}.paraui-v4-field-form-control-input-content .text-field-error-text{display:none}.paraui-v4-field-form-helper-text{line-height:20px;word-break:break-all}.paraui-v4-field-form-helper-text .is-warning>.paraui-v4-helper-text.paraui-v4-helper-text-error{color:#ff9326}
+@charset "UTF-8";.paraui-v4-field-form-item{vertical-align:top}.paraui-v4-field-form-item.is-horizontal{display:flex}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label{flex-shrink:0;padding:0;margin-right:8px;text-align:end}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-left{text-align:start}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-multiline .paraui-v4-field-form-label-comp{display:inline-block}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label-comp{display:inline-flex;align-items:center;width:100%;max-width:100%;min-height:32px;margin:0}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-content.has-spacing{margin-bottom:16px}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-control-input{min-height:24px}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-helper-text{min-height:16px;line-height:16px}.paraui-v4-field-form-content{flex:1}.paraui-v4-field-form-content.has-spacing{margin-bottom:20px}.paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-control-input{display:flex;align-items:center;min-height:32px}.paraui-v4-field-form-control-input-content{width:100%}.paraui-v4-field-form-control-input-content .paraui-v4-radio-group>.radio-group-content .radio-item-box{margin-bottom:0}.paraui-v4-field-form-control-input-content .text-field-error-text:not(.paraui-v4-helper-text-force-visible),.paraui-v4-field-form-control-input-content .select-error-text:not(.paraui-v4-helper-text-force-visible){display:none}.paraui-v4-field-form-helper-text{line-height:20px;word-break:break-all}.paraui-v4-field-form-helper-text .is-warning>.paraui-v4-helper-text.paraui-v4-helper-text-error{color:#ff9326}

package/es/FieldForm/index.d.ts

@@ -19,3 +19,5 @@ declare const FieldForm: CompoundedComponent;
 export type { ErrorListProps, FieldFormInstance, FieldFormItemProps, FieldFormListFieldData, FieldFormListOperation, FieldFormListProps, FieldFormProps, Rule, RuleObject, RuleRender };
 export default FieldForm;
 export type * from './interface';
+export { joinNamePath } from './util';
+export { PARA_UI_COMPACT_CONTROL_MARKER } from './compactControlMarker';

package/es/FieldForm/index.js

@@ -1,21 +1,25 @@
 import { FormProvider as o } from "./context.js";
 import m from "./Form.js";
 import t from "./ErrorList.js";
-import i from "./FieldFormItem/index.js";
-import e from "./FormList.js";
+import e from "./FieldFormItem/index.js";
+import i from "./FormList.js";
 import s from "./hooks/useFormInstance.js";
 import './index.css';/* empty css           */
-import F from "./hooks/useForm.js";
-import { useWatch as p } from "rc-field-form";
+import { joinNamePath as R } from "./util.js";
+import { PARA_UI_COMPACT_CONTROL_MARKER as h } from "./compactControlMarker.js";
+import p from "./hooks/useForm.js";
+import { useWatch as F } from "rc-field-form";
 const r = m;
-r.Item = i;
-r.List = e;
+r.Item = e;
+r.List = i;
 r.ErrorList = t;
-r.useForm = F;
+r.useForm = p;
 r.useFormInstance = s;
-r.useWatch = p;
+r.useWatch = F;
 r.Provider = o;
 export {
-  r as default
+  h as PARA_UI_COMPACT_CONTROL_MARKER,
+  r as default,
+  R as joinNamePath
 };
 //# sourceMappingURL=index.js.map

package/es/FieldForm/interface.d.ts

@@ -1,2 +1,11 @@
+import { ReactNode } from 'react';
 export type { InternalNamePath, NamePath, Store, StoreValue } from 'rc-field-form/lib/interface';
 export type FormLabelAlign = 'left' | 'right';
+export interface ItemDecoratorMeta {
+    namePath: (string | number)[];
+    path: string;
+}
+export interface ItemDecorator {
+    getItemClassName?: (meta: ItemDecoratorMeta) => string | undefined | false;
+    renderItemExtra?: (meta: ItemDecoratorMeta) => ReactNode;
+}

package/es/FieldForm/style/index.css

@@ -1 +1 @@
-.paraui-v4-field-form-item{vertical-align:top}.paraui-v4-field-form-item.is-horizontal{display:flex}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label{margin-right:8px;padding:0;flex-shrink:0;text-align:end}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-left{text-align:start}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-multiline .paraui-v4-field-form-label-comp{display:inline-block}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label-comp{width:100%;display:inline-flex;align-items:center;margin:0;max-width:100%;min-height:32px}.paraui-v4-field-form-content{flex:1}.paraui-v4-field-form-content.has-spacing{margin-bottom:20px}.paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-control-input{display:flex;align-items:center;min-height:32px}.paraui-v4-field-form-control-input-content{width:100%}.paraui-v4-field-form-control-input-content .paraui-v4-radio-group>.radio-group-content .radio-item-box{margin-bottom:0}.paraui-v4-field-form-control-input-content .text-field-error-text{display:none}.paraui-v4-field-form-helper-text{line-height:20px;word-break:break-all}.paraui-v4-field-form-helper-text .is-warning>.paraui-v4-helper-text.paraui-v4-helper-text-error{color:#ff9326}
+.paraui-v4-field-form-item{vertical-align:top}.paraui-v4-field-form-item.is-horizontal{display:flex}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label{flex-shrink:0;padding:0;margin-right:8px;text-align:end}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-left{text-align:start}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label.is-multiline .paraui-v4-field-form-label-comp{display:inline-block}.paraui-v4-field-form-item.is-horizontal .paraui-v4-field-form-label-comp{display:inline-flex;align-items:center;width:100%;max-width:100%;min-height:32px;margin:0}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-content.has-spacing{margin-bottom:16px}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-field-form-control-input{min-height:24px}.paraui-v4-field-form-item.is-spacing-compact .paraui-v4-helper-text{min-height:16px;line-height:16px}.paraui-v4-field-form-content{flex:1}.paraui-v4-field-form-content.has-spacing{margin-bottom:20px}.paraui-v4-field-form-content.has-spacing.has-helper-text{margin-bottom:0}.paraui-v4-field-form-control-input{display:flex;align-items:center;min-height:32px}.paraui-v4-field-form-control-input-content{width:100%}.paraui-v4-field-form-control-input-content .paraui-v4-radio-group>.radio-group-content .radio-item-box{margin-bottom:0}.paraui-v4-field-form-control-input-content .text-field-error-text:not(.paraui-v4-helper-text-force-visible),.paraui-v4-field-form-control-input-content .select-error-text:not(.paraui-v4-helper-text-force-visible){display:none}.paraui-v4-field-form-helper-text{line-height:20px;word-break:break-all}.paraui-v4-field-form-helper-text .is-warning>.paraui-v4-helper-text.paraui-v4-helper-text-error{color:#ff9326}

package/es/FieldForm/util.d.ts

@@ -13,9 +13,23 @@ export declare function toArray<T>(candidate?: T | T[] | false): T[];
  * @returns string
  */
 export declare function getFieldId(namePath: InternalNamePath, formName?: string): string | undefined;
+/**
+ * 拼接 namePath 为 path 字符串，数组下标用方括号
+ * @example joinNamePath(['ubr', 'list', 0, 'x']) => 'ubr.list[0].x'
+ */
+export declare function joinNamePath(namePath: (string | number)[]): string;
 /**
  * 通过 meta 或传递的 validateStatus 获取合并后的状态
  */
 export declare function getStatus<DefaultValue>(errors: ReactNode[], warnings: ReactNode[], meta: Meta, defaultValidateStatus: ValidateStatus | DefaultValue, hasFeedback?: boolean, validateStatus?: ValidateStatus): ValidateStatus | DefaultValue;
 export declare function isReactComponent(element: React.ReactElement): boolean;
 export declare function isDOMElement(element: React.ReactElement): boolean;
+/**
+ * 判断表单项的直接子节点是否为 Switch/Checkbox 这类矮控件（含 React.memo 包裹场景，
+ * 以及消费方对 Switch/Checkbox 做二次封装、但透传了 PARA_UI_COMPACT_CONTROL_MARKER
+ * 标记的包装组件），用于在调用方未显式传 spacing 时自动选中 compact 档，替代此前
+ * 完全依赖手写 opt-in 的方式。仅识别单一直接子节点；children 为多个节点、或非合法
+ * element（如纯文本）时一律判定为不匹配，交由默认 normal 档处理，避免对组合型字段
+ * 做出错误猜测。
+ */
+export declare function isCompactControlChild(children: ReactNode): boolean;

package/es/FieldForm/util.js

@@ -1,25 +1,49 @@
-import { isValidElement as s } from "react";
-const f = ["parentNode"], u = "field-form_item";
-function g(e) {
-  return e === void 0 || e === !1 ? [] : Array.isArray(e) ? e : [e];
+import u, { isValidElement as f } from "react";
+import { Switch as s } from "../Switch/index.js";
+import { Checkbox as c } from "../Checkbox/index.js";
+import { PARA_UI_COMPACT_CONTROL_MARKER as m } from "./compactControlMarker.js";
+const a = ["parentNode"], y = "field-form_item";
+function $(t) {
+  return t === void 0 || t === !1 ? [] : Array.isArray(t) ? t : [t];
 }
-function a(e, r) {
-  if (!e.length)
+function T(t, r) {
+  if (!t.length)
     return;
-  const t = e.join("_");
-  return r ? `${r}_${t}` : f.includes(t) ? `${u}_${t}` : t;
+  const e = t.join("_");
+  return r ? `${r}_${e}` : a.includes(e) ? `${y}_${e}` : e;
 }
-function d(e, r, t, n, l, o) {
-  let i = n;
-  return o !== void 0 ? i = o : t.validating ? i = "validating" : e.length ? i = "error" : r.length ? i = "warning" : (t.touched || l && t.validated) && (i = "success"), i;
+function E(t) {
+  return t.reduce(
+    (r, e) => typeof e == "number" ? `${r}[${e}]` : r ? `${r}.${e}` : String(e),
+    ""
+  );
 }
-function p(e) {
-  return s(e) && (typeof e.type == "function" || typeof e.type == "object");
+function M(t, r, e, i, l, n) {
+  let o = i;
+  return n !== void 0 ? o = n : e.validating ? o = "validating" : t.length ? o = "error" : r.length ? o = "warning" : (e.touched || l && e.validated) && (o = "success"), o;
+}
+function I(t) {
+  return f(t) && (typeof t.type == "function" || typeof t.type == "object");
+}
+const d = /* @__PURE__ */ Symbol.for("react.memo");
+function p(t) {
+  return t !== null && typeof t == "object" && t.$$typeof === d ? t.type : t;
+}
+const C = [s, c];
+function R(t) {
+  const r = u.Children.toArray(t);
+  if (r.length !== 1) return !1;
+  const e = r[0];
+  if (!f(e)) return !1;
+  const i = p(e.type);
+  return C.includes(i) ? !0 : typeof i == "function" && i[m] === !0;
 }
 export {
-  a as getFieldId,
-  d as getStatus,
-  p as isReactComponent,
-  g as toArray
+  T as getFieldId,
+  M as getStatus,
+  R as isCompactControlChild,
+  I as isReactComponent,
+  E as joinNamePath,
+  $ as toArray
 };
 //# sourceMappingURL=util.js.map

package/es/FormItemGroup/component.json

@@ -0,0 +1,72 @@
+{
+    "name": "FormItemGroup",
+    "category": "Layout",
+    "description": "表单项堆叠容器：官方推荐的字段间纵向/横向间距方案。字段自带的 20px 间距基线（helper-text 占位）原本要外层手动挂 `.paraui-v4-form` 类名才会生效，容易被忘记导致字段在 flex 布局下零间距；FormItemGroup 把这条基线内置在自己身上，不用再记类名。同时内部 gap 只认自身 CSS 变量（!important），裸写 style.gap 不会生效，用来替代业务/AI 随手在字段外层加 gap 导致的间距叠加问题（基线已经占了 20px，外层再加 gap 会翻倍）。一个组件同时兜住「漏挂基线类→零间距」和「叠加 gap→翻倍」两个方向。",
+    "semantic": {
+        "intent": ["表单字段堆叠", "受控间距容器", "间距基线兜底"],
+        "useCases": [
+            "多个 TextField/Select/Switch 等字段手写堆叠（最常见场景，不依赖 Form/FieldForm）",
+            "多个 FormItem/FieldFormItem 纵向堆叠(direction='vertical'，默认)",
+            "少量字段并排展示(direction='horizontal')",
+            "需要在字段之间加统一间距的场景(gap 属性)"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "vertical": {
+            "meaning": "默认值。`display:flex; flex-direction:column`，字段自上而下堆叠。"
+        },
+        "horizontal": {
+            "meaning": "`display:flex; flex-direction:row`，字段并排展示。"
+        }
+    },
+    "states": ["default"],
+    "idealProps": {
+        "direction": {
+            "type": "enum",
+            "values": ["vertical", "horizontal"],
+            "default": "vertical",
+            "description": "排列方向。表单场景基本用默认的 'vertical'。"
+        },
+        "gap": {
+            "type": "number",
+            "default": 0,
+            "description": "字段间距(px)，默认 0——不额外加间距，完全依赖字段自身已有的间距（如 helper-text 占位）。真正需要更大间距时才传这个值，例如 gap={32}。"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "子元素，通常是若干个 FormItem / FieldFormItem。"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层根 div 的类名。"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层根 div 的内联样式。注意其中的 gap 不会生效（会被组件内部 !important 规则覆盖），间距请用 gap 属性。"
+        }
+    },
+    "do": [
+        "字段纵向堆叠用 <FormItemGroup> 替代手写 <div style={{ display:'flex', flexDirection:'column', gap: 16 }}>",
+        "用 <FormItemGroup> 包住字段就自动拿到 20px 间距基线，不需要再额外记着给外层容器挂 `.paraui-v4-form` 类名",
+        "确实需要比字段自带间距更大的间距时，用 gap 属性：<FormItemGroup gap={32}>",
+        "字段并排展示用 direction='horizontal'"
+    ],
+    "dont": [
+        "不要在 style 里直接写 gap，例如 <FormItemGroup style={{ gap: 16 }}>——会被内部规则忽略，且不会有任何视觉效果，请改用 gap 属性",
+        "不要在没有堆叠需求的单个字段外面套一层 FormItemGroup，纯粹是多余包裹",
+        "确实需要密集布局下零间距（如表格内联编辑），仍可以用更具体的选择器覆盖 min-height（这条基线规则没有 !important），不需要绕开 FormItemGroup"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "style.gap 不会生效，是设计上的行为而不是 bug",
+            "wrong": "<FormItemGroup style={{ gap: 16 }}>...</FormItemGroup>  // 不生效，且不会报 TS 错误，容易被误以为生效了",
+            "right": "<FormItemGroup gap={16}>...</FormItemGroup>  // 通过 gap 属性设置，实际生效"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FormItemGroup",
+        "adapter": null
+    }
+}

package/es/FormItemGroup/index.css

@@ -0,0 +1 @@
+@charset "UTF-8";.paraui-v4-form-item-group{display:flex;gap:var(--paraui-v4-form-item-group-gap, 0)!important}.paraui-v4-form-item-group.paraui-v4-form-item-group-vertical{flex-direction:column}.paraui-v4-form-item-group.paraui-v4-form-item-group-horizontal{flex-direction:row}.paraui-v4-form-item-group .paraui-v4-helper-text{min-height:20px}

package/es/FormItemGroup/index.d.ts

@@ -0,0 +1,14 @@
+import { default as React, FunctionComponent, ReactNode } from 'react';
+export interface FormItemGroupProps {
+    /** 样式class */
+    className?: string;
+    /** style（其中的 gap 不会生效，请用 gap 属性设置间距） */
+    style?: React.CSSProperties;
+    /** 排列方向，默认 'vertical'（纵向堆叠，最常见的表单场景） */
+    direction?: 'vertical' | 'horizontal';
+    /** 字段间距（px），默认 0——即完全依赖字段自身已有的间距，不额外加间距 */
+    gap?: number;
+    children?: ReactNode;
+}
+declare const FormItemGroup: FunctionComponent<FormItemGroupProps>;
+export default FormItemGroup;

package/es/FormItemGroup/index.js

@@ -0,0 +1,27 @@
+import { j as n } from "../_virtual/jsx-runtime.js";
+import c from "clsx";
+import { $prefixCls as o } from "../GlobalContext/constant.js";
+import './index.css';/* empty css           */
+const x = (t) => {
+  const { className: p, style: r, children: e, direction: m = "vertical", gap: s = 0, ...i } = t;
+  process.env.NODE_ENV !== "production" && r && "gap" in r && console.warn(
+    "[FormItemGroup] style.gap 不会生效，组件内部的 gap 规则带 !important，只认 gap 属性。请使用 <FormItemGroup gap={number}> 设置间距。"
+  );
+  const a = {
+    ...r,
+    [`--${o}-form-item-group-gap`]: `${s}px`
+  };
+  return /* @__PURE__ */ n.jsx(
+    "div",
+    {
+      className: c(`${o}-form-item-group ${o}-form-item-group-${m}`, p),
+      style: a,
+      ...i,
+      children: e
+    }
+  );
+};
+export {
+  x as default
+};
+//# sourceMappingURL=index.js.map

package/es/FormItemGroup/style/css.js

@@ -0,0 +1 @@
+import './index.css';

package/es/FormItemGroup/style/index.css

@@ -0,0 +1 @@
+.paraui-v4-form-item-group{display:flex;gap:var(--paraui-v4-form-item-group-gap, 0) !important}.paraui-v4-form-item-group.paraui-v4-form-item-group-vertical{flex-direction:column}.paraui-v4-form-item-group.paraui-v4-form-item-group-horizontal{flex-direction:row}.paraui-v4-form-item-group .paraui-v4-helper-text{min-height:20px}

package/es/FormItemGroup/style/index.js

@@ -0,0 +1 @@
+import './index.css';

package/es/HelperText/index.js

@@ -1,23 +1,25 @@
-import { j as p } from "../_virtual/jsx-runtime.js";
-import { $prefixCls as s } from "../GlobalContext/constant.js";
+import { j as u } from "../_virtual/jsx-runtime.js";
+import { useContext as a } from "react";
+import { $prefixCls as t } from "../GlobalContext/constant.js";
+import { FormItemInputContext as x } from "../FieldForm/context.js";
 import './index.css';/* empty css           */
-const x = (o) => {
-  const { className: e, style: n, error: t = !1, hideErrorDom: l = !1, helperText: a } = o;
-  if (l === null || !t && l) return null;
-  const i = () => {
-    let r = `${s}-helper-text`;
-    return e && (r += ` ${e}`), t && (r += ` ${s}-helper-text-error`), r;
+const $ = (r) => {
+  const { className: o, style: i, error: l = !1, helperText: m } = r, { isFormItemInput: n } = a(x), s = r.hideErrorDom !== void 0 ? r.hideErrorDom : n ? null : !1;
+  if (s === null || !l && s) return null;
+  const f = () => {
+    let e = `${t}-helper-text`;
+    return o && (e += ` ${o}`), l && (e += ` ${t}-helper-text-error`), r.hideErrorDom === !1 && (e += ` ${t}-helper-text-force-visible`), e;
   };
-  return /* @__PURE__ */ p.jsx(
+  return /* @__PURE__ */ u.jsx(
     "p",
     {
-      className: i(),
-      style: n,
-      children: a
+      className: f(),
+      style: i,
+      children: m
     }
   );
 };
 export {
-  x as default
+  $ as default
 };
 //# sourceMappingURL=index.js.map

package/es/Menu/component.json

@@ -116,12 +116,14 @@
         "配置 shrinkOthers 以提升用户查找效率",
         "使用 icon 辅助识别菜单项",
         "**菜单数据通过 menuListProps.list 传入**（不是顶层 list prop）：`<Menu menuListProps={{ list: menuData }} />`，menuData 是 MenuChildrenProps[] 数组",
-        "MenuChildrenProps 核心字段（src/Menu/interface.ts:25-63）：`label: ReactNode`（菜单名），`path: string`（路径，与 selectMenu 比对高亮），`icon: ReactNode`（图标），`children: MenuChildrenProps[]`（子菜单），`type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'`（菜单类型），`href: string`（a 标签地址），`badge: ReactNode`（标记）"
+        "MenuChildrenProps 核心字段（src/Menu/interface.ts:25-63）：`label: ReactNode`（菜单名），`path: string`（路径，与 selectMenu 比对高亮），`icon: ReactNode`（图标），`children: MenuChildrenProps[]`（子菜单），`type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'`（菜单类型），`href: string`（a 标签地址），`badge: ReactNode`（标记）",
+        "`group: boolean`（仅一级生效,需同时有 children）：把该项渲染成不可点击的纯文本分组小标题,children 常驻展开且按顶层菜单项样式渲染（不缩进,可配 icon）。示例：`{ label: '路由管理', group: true, children: [{ label: '路由规则', path: '/router/rule' }, { label: '静态资源', path: '/router/static' }] }`"
     ],
     "dont": [
         "在菜单项中放置非导航类的复杂交互组件",
         "过度使用动态生成的菜单导致性能问题",
-        "把菜单数据传给顶层 list prop——Menu 没有顶层 list prop,数据必须通过 menuListProps.list 传入"
+        "把菜单数据传给顶层 list prop——Menu 没有顶层 list prop,数据必须通过 menuListProps.list 传入",
+        "不要在非一级菜单项或没有 children 的项上设置 group: true——不满足条件会被忽略,自动退化为原有渲染（普通叶子节点 / 普通折叠子菜单）,不会报错但也不会生效"
     ],
     "events": {
         "onClickMenu": {
@@ -171,6 +173,11 @@
             "issue": "color prop 只有 'deep' 和 'light' 两个有效值(ColorType),传其他字符串 TS 报错",
             "wrong": "color='dark'  // TS2322: Type '\"dark\"' is not assignable to type 'ColorType'",
             "right": "color='deep'  // 合法值: 'deep'(深色主题) | 'light'(浅色主题)"
+        },
+        {
+            "issue": "group 生效需同时满足两个前提：该项是一级菜单（level 1）且自身有 children；在二级菜单项或没有 children 的项上设置 group: true 会被静默忽略,自动退化为原渲染,容易被误以为是 bug",
+            "wrong": "// 二级菜单项上设置 group,不会生效\n{ label: '一级', children: [{ label: '二级', group: true, children: [...] }] }",
+            "right": "// group 只能设在一级菜单项上\n{ label: '路由管理', group: true, children: [{ label: '路由规则', path: '/router/rule' }] }"
         }
     ],
     "mapping": {